# 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

- Message body

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