Placing a call

When placing a call, use nccPlaceCall to send an INVITE request.

Prototype

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.

SIP message information structure

When an application calls nccPlaceCall, the SIP stack sends an INVITE. The NCC SIP message structure has two components:

Message header

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.

Message body

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.

Examples

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);