Adding a new header

From reSIProcate
Revision as of 13:57, 3 September 2008 by Bcampen (talk | contribs) (Removing some text; the build system does this automatically.)

Jump to: navigation, 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

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 ????"),

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

Defines a header that has a single value.

defineMultiHeader

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

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

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

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

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

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.