Adding a new header

From reSIProcate
Jump to navigation Jump to search

NOTE that proprietary or experimental headers may be better added at runtime rather than at compile time. See Extension Header.

NOTE that you MUST update the gperf hash description files and run the test drivers to ensure that the new hash function works as intended.

HeaderTypes.hxx[edit]

Defines an enum for the header and determines where the header appears in the message. Choose a define macro according to the requirements of the header. In either case, the macro arguments are:

  1. headerName; e.g. IdentityInfo
  2. RFC-header-name; e.g. Identity-Info
  3. resip header class; e.g. GenericURI
  4. constant string of draft or RFC; e.g. "draft-sip-identity-03"

For example:

defineHeader(IdentityInfo, "Identity-Info", GenericURI, "draft-sip-identity-03"),

For example:

defineMultiHeader(AllowEvents, "Allow-Events", Token, "RFC 3265"),

Note that the macro is followed by a comma in this file.

The header declared will be available using the access token named h_ followed by the headerName. This access token will be used in the usual way from SipMessage, via the header, exists, and remove methods. For multi-headers, the access token is named h_ followed the headerName pluralized. If your header ends in an "s" or has irregular pluralization, you will need to add a typedef for the correct pluralization in Headers.cxx. For example:

H_SecurityVerifys resip::h_SecurityVerifies;

defineHeader[edit]

Defines a header that has a single value.

defineMultiHeader[edit]

Defines a header that may have mulitple values. That is, the header values can be comma separated or the header can appear multiple times in a message.

The type in the define macro is wrapped in a collection. The resip name of the resulting collection type is the plural form of the typename. E.g. GenericURIs. The actual type is ParserContainer<GenericURI>.

Headers.hxx[edit]

Each header resip type has a section where headers of that type are declared. Add the same macro call here that you just added to HeaderTypes.hxx. Make sure you the macro call is followed by a semi-colon.

Headers.cxx[edit]

Each header resip type has a section where headers of that type are declared. Add the same macro call here that you just added to HeaderTypes.hxx. Make sure you the macro call is followed by a semi-colon.

If your header ends in an "s" or has irregular pluralization, you will need to add a typedef for the correct pluralization in Headers.cxx. For example:

H_SecurityVerifys resip::h_SecurityVerifies;

HeaderHash.gperf[edit]

This file maps from the SIP name to the resip name. Add your entry to the end before the %%. Each entry is on its own line. The line you add must be the RFC-header-name from the macro followed by ", Headers::" followed by headerName from the macro.

For example, the entry for Identity-Info is: identity-info, Headers::IdentityInfo

SipMessage.hxx[edit]

Add that same macro to the SipMessage class declaration near the other headers. Order is not important except that the macro call must be after the macro definitions. Make sure you the macro call is followed by a semi-colon.

SipMessage.cxx[edit]

Add that same macro to the SipMessage class definition near the other headers. Order is not important except that the macro call must be after the macro definitions. Make sure you the macro call is followed by a semi-colon.

Maybe add the new header to SipMessage::mergeUri. The form of the merge call for a new header is to call merge on the resip header access token for the header. For example:

 h_ProxyRequires.merge(*this, source.embedded());

Note the plural form of the resip header access token for the multi-header case. Merge for multi-headers concatenates the two header lists. For the non-multi-header case, the merged in header value replaces the target's header value.