Filter
Top Products
Dialogic
®
Global Call IP Technology Guide — November 2007 183
Dialogic Corporation
IP-Specific Operations
4.9.5 Setting SIP Header Fields for Outbound Messages
Note that it is not necessary for applications to register in advance the header field types that it will
be setting (as described in Section 4.9.4, “Registering SIP Header Fields to be Retrieved”, on
page 180). Registration of header field names is only required when the application needs to
retrieve those header fields from received messages.
Assuming that SIP message information access was enabled when the virtual board was started,
applications set SIP message header fields by inserting the set ID/parm ID and value string for each
field being set into a GC_PARM_BLK using gc_util_insert_parm_ref_ex( ) or
gc_util_insert_parm_val( ), and then either setting the header fields for the next message to be
sent by calling the gc_SetUserInfo( ) function or immediately sending the message by calling
gc_Extension( ) or another Global Call function that causes a SIP message to be sent.
When calling gc_SetUserInfo( ) to preset SIP message header fields (which is only recommended
when using the gc_MakeCall( ) function), the duration parameter must be set to
GC_SINGLECALL, and the information is not transmitted until the next Global Call function that
sends a SIP message is issued. Note that the preset header fields will be sent in the next SIP
message, so that the application must ensure that no other Global Call function is called before
gc_MakeCall( ).
Calling the gc_SetUserInfo( ) function results in the following behavior:
• SIP message header fields that are set do not take effect until gc_MakeCall( ) or another
function that transmits a SIP message is issued.
• Using the gc_SetUserInfo( ) does not affect incoming SIP messages on the same channel.
• Any SIP message header fields that are set only affect the next Dialogic
®
Global Call API
function call.
• The gc_SetUserInfo( ) function fails with GC_ERROR if the sip_msginfo_mask field in the
IP_VIRTBOARD structure is not set to IP_SIP_MSGINFO_ENABLE. When
gc_ErrorInfo( ) is called in this case, the error code is IPERR_BAD_PARAM.
The gc_Extension( ) function is typically used when sending supplementary SIP messages, such as
INFO or OPTIONS. It is possible to use the gc_SetUserInfo( ) function to set the header field
before sending the message with the gc_Extension( ) function call or other function that directly
produces a SIP request (such as gc_ReqService( ) for SIP REGISTER requests), but that approach
is not recommended. This is the case because the preset header fields will be used in the very next
SIP message that is sent, so the application must ensure that no other Global Call function is called
before the intended function.
Refer to Table 8, “Common Header Fields in Outbound SIP Messages”, on page 173, to see the
correspondence between the most common SIP header fields, the supported SIP messages in which
these header fields are commonly set, and the Global Call functions that are called to transmit these
messages.
Applications should use the IPSET_SIP_MSGINFO set ID and the IPPARM_SIP_HDR parameter
ID when setting SIP header fields in the GC_PARM_BLK. This same set ID/parm ID pair can be
used to set any settable SIP header field, whether it is a required field, an optional one, or a
proprietary one. In each case, the parameter value that is inserted into the parameter block is a