When placing a call, use nccPlaceCall to send an INVITE request.
DWORD nccPlaceCall ( CTAHD linehd, char *calledaddr, char *callingaddr, void *mgrcallparms, void *protcallparms, NCC_CALLHD *callhd)
Argument |
Description |
linehd |
Line handle used to open the NCC service instance. |
calledaddr |
Not used, but cannot be NULL. |
callingaddr |
Not used. |
mgrcallparms |
Pointer to the SIP message information structure. |
protcallparms |
Not used. |
callhd |
Pointer to NCC_CALLHD. NCC assigns a valid call handle to a successfully initialized outbound call. |
When an application calls nccPlaceCall, the SIP stack sends an INVITE. The NCC SIP message structure has two components:
Message header
Message body
The following table lists the required information elements (IEs) associated with the message header when nccPlaceCall is used:
Information element (IE) |
Description |
Message header information for SIP Request |
|
SIP_IE_TO_FULL_ADDRESS |
SIP URI of the called user. |
SIP_IE_FROM_FULL_ADDRESS |
SIP URI of the calling user. |
Two methods are available to create the message body:
Method |
Description |
Transparent IEs |
Formats the entire message body as a string and includes the string as the SIP_IE_BODY element. The content-type header must be included so that the correct information appears in the SIP header. Refer to SIP information elements for a list. |
SIP IEs |
Uses pre-defined SIP IEs to add session description protocol (SDP) information to the message. Refer to SIP information element values for a list of pre-defined values. |
SIP messages may contain multiple message bodies. Use the Transparent IE method to send a SIP message with multiple bodies. Precede each body being sent with a SIP_IE_CONTENT_TYPE header. Use the NCC_SIP_INFO_ADD_DATA macro to send binary bodies; for example, SIP-T, requires the use of binary bodies. When receiving a message with multiple bodies, a content length and content type IE precedes each received body IE.
You can also create a SIP message that does not have a body and includes only message headers. For example, the only IEs in a SIP INVITE request made using nccPlaceCall can be the To and From address IEs.
The following table lists the optional information elements (IEs) for the message body:
Information element (IE) |
Description |
Information for SIP message body using Transparent IEs |
|
SIP_IE_CONTENT_TYPE |
Content-type header in the SIP message. |
SIP_IE_BODY |
Body of message. |
SDP information for SIP message body using SIP IEs |
|
SIP_IE_SDP_ORIGIN_USERNAME |
User name in the origin field. |
SIP_IE_SDP_ORIGIN_SESSION_ID |
Session ID in the origin field. |
SIP_IE_SDP_ORIGIN_VERSION |
Version number in the origin field. |
SIP_IE_SDP_ORIGIN_ADDRESS |
Address in the origin field. |
SIP_IE_SDP_SESSION_NAME |
Session name. |
SIP_IE_SDP_CONNECTION_NET_TYPE |
Network type: typically IN for Internet. |
SIP_IE_SDP_CONNECTION_ADDR_TYPE |
Address type: IP4 |
SIP_IE_SDP_CONNECTION_ADDRESS |
Connection address in the following format: n.n.n.n where n.n.n.n is an IP address. |
SIP_IE_SDP_MEDIA_TYPE |
Media type. For valid values, refer to SIP_IE_SDP_MEDIA_TYPE. |
SIP_IE_SDP_MEDIA_PORT |
Media port. For valid values, refer to SIP_IE_SDP_MEDIA_PORT. |
SIP_IE_SDP_MEDIA_PROTOCOL |
Media protocol. For valid values, refer to SIP_IE_SDP_MEDIA_PROTOCOL. |
SIP_IE_SDP_ENCODING |
Encoding. Use multiple entries if required. For valid values, refer to SIP_IE_SDP_ENCODING. |
Although you can receive a message with SIP_IE_CONTENT_LENGTH, it is not necessary to include this IE when calling an NCC function that causes a SIP message to be sent. Specify the actual body length when passing body data using NCC_SIP_INFO_ADD_DATA.
The following coding example illustrates how to add SDP information using transparent IEs to a SIP IE buffer before calling nccPlaceCall:
// Add message SDP body using transparent IEs
//
DWORD b[256];
char bb[512];
char version[80], owner1[80], owner2[80], session[80], connection[80], time[80];
char media[80];
static char digits[40] = "0"
sprintf(version, "v=0\r\n");
sprintf(owner1, "o=user 01234567890 0987654321 IN IP4");
sprintf(owner2, "sip:user@192.162.2.2:5060\r\n");
sprintf(session, "s=NMS SIP\r\n");
sprintf(connection, "c= IN IP4 192.168.2.2\r\n");
sprintf(time, "t=0 0\r\n");
sprintf(media, "m=audio 8006 RTP/AVP 0 8 3\r\n");
strcpy(bb, version);
strcat(bb, owner1);
strcat(bb, owner2);
strcat(bb, session);
strcat(bb, connection);
strcat(bb, time);
strcat(bb, media);
NCC_SIP_INFO_ADD_STR ( b, &ie, SIP_IE_CONTENT_TYPE, "application/SDP" );
NCC_SIP_INFO_ADD_DATA ( b, &ie, SIP_IE_BODY, bb, strlen(bb) );
ret = nccPlaceCall( ctahd, digits, NULL, b, NULL, &callhd);
The following code example illustrates how to add SDP information using SIP IEs:
NCC_SIP_INFO_ADD_STR ( b, &ie, SIP_IE_SDP_ORIGIN_USERNAME, "user" );
NCC_SIP_INFO_ADD_STR ( b, &ie, SIP_IE_SDP_ORIGIN_SESSION_ID, "01234567890" );
NCC_SIP_INFO_ADD_STR ( b, &ie, SIP_IE_SDP_ORIGIN_VERSION, "0987654321" );
NCC_SIP_INFO_ADD_STR ( b, &ie, SIP_IE_SDP_ORIGIN_ADDRESS, "sip:user@192.162.2.2:5060");
NCC_SIP_INFO_ADD_STR ( b, &ie, SIP_IE_SDP_SESSION_NAME, "NMS SIP" );
NCC_SIP_INFO_ADD_STR ( b, &ie, SIP_IE_SDP_CONNECTION_NET_TYPE, "IN" );
NCC_SIP_INFO_ADD_STR ( b, &ie, SIP_IE_SDP_CONNECTION_ADDR_TYPE, "IP4" );
NCC_SIP_INFO_ADD_STR ( b, &ie, SIP_IE_SDP_CONNECTION_ADDRESS, "192.168.2.2" );
NCC_SIP_INFO_ADD_NUM ( b, &ie, SIP_IE_SDP_MEDIA_TYPE, SDP_MEDIA_TYPE_AUDIO );
NCC_SIP_INFO_ADD_NUM ( b, &ie, SIP_IE_SDP_MEDIA_PORT, 8006 );
NCC_SIP_INFO_ADD_NUM ( b, &ie, SIP_IE_SDP_MEDIA_PROTOCOL, SDP_MEDIA_PROTOCOL_RTP );
NCC_SIP_INFO_ADD_NUM ( b, &ie, SIP_IE_SDP_ENCODING, 0 );
NCC_SIP_INFO_ADD_NUM ( b, &ie, SIP_IE_SDP_ENCODING, 8 );
NCC_SIP_INFO_ADD_NUM ( b, &ie, SIP_IE_SDP_ENCODING, 3 );
ret = nccPlaceCall( ctahd, digits, NULL, b, NULL, &callhd);