SIP for NCC API functions

NCC is a call control API that spans numerous telephony protocols. From a call control protocol perspective, the SIP for NCC API functions are a subset of the NCC functions. However, both the message body of SIP and the URI addresses in the protocol require a different treatment than those used in traditional telephony protocols.

The SIP for NCC API implementation makes use of the pointers to a buffer contained in the NCC function calls. The data in these buffers is function specific, but the general format is the same across those functions that accept these arguments.

Data structure formats

As shown in the following buffer illustration, the first word of the data structure is a DWORD that contains the length of data passed in the buffer. An array of NCC_SIP_INFO data structures follows the DWORD.

structure.gif

The definition of an NCC_SIP_INFO structure is as follows:

typedef struct
{
WORD         tag;   
WORD         size;
union
{
DWORD       number;
BYTE        buffer[1];     
} d;
} NCC_SIP_INFO;

The first element of the structure is a tag that identifies the element type followed by the size and the data. The data element is either a DWORD or a data array; the data array is usually a string. The NCC_SIP_INFO structure specifies a SIP information element (IE).

Creating data structures

The nccxsip.h header file includes a set of macros for creating message buffers used by NCC API calls. To initialize the data buffer, use NCC_SIP_INFO_INIT. To add data, use NCC_SIP_INFO_ADD_STR, NCC_SIP_INFO_ADD_NUM, or NCC_SIP_INFO_ADD_DATA. The following example illustrates this procedure:

DWORD            b[256];                                 // data buffer
NCC_SIP_INFO     *ie;                                    // work pointer
NCC_SIP_INFO_INIT    ( b, &ie );                         // initialize
NCC_SIP_INFO_ADD_STR ( b, &ie, SIP_IE_TO_FULL_ADDRESS,
    sip:calleduser@1.1.1.:5060);                         // add first SIP IE to buffer
NCC_SIP_INFO_ADD_STR ( b, &ie, SIP_IE_FROM_FULL_ADDRESS,
    sip:callinguser@1.1.1.2:5060);                       // add second SIP IE to buffer
NCC_SIP_INFO_ADD_NUM ( b, &ie, SIP_IE_SDP_ENCODING, 0 ); // add third SIP IE to buffer

This example contains some of the information that is passed to nccPlaceCall. The first two information elements (IEs) are the To (called party) and From (calling party) URLs. The IEs are copied to the SIP message header of an INVITE message that is the result of the NCC function call. The other piece of information is the session description protocol (SDP) encoding information. From an NCC perspective, this information is referred to as SIP information elements (SIP IEs).