(Page 1 of 1 in this chapter)

Appendix D

Sending and Receiving Raw Q.931 Data

Introduction

AG ISDN version 1.2 allows an application to include raw Q.931 data in one or more completely custom-built information elements (IEs) in messages sent to the stack. These information elements, called transparent IEs, are inserted verbatim in the Q.931 message generated by the stack. This specification method allows an application access to IEs, and fields in IEs, that cannot be accessed using the macros associated with ACU messages. This method can be used to specify both standard IEs (codeset 0) and extensions (i.e. codeset 6 and 7).
An application can also access and read the raw data in an incoming Q.931 message, rather than reading returned values for specific fields in data structures.

Creating Transparent IEs

The application supplies the data (in hexadecimal format) for the transparent IEs in a buffer referenced in one of the usual ACU messages. The following macros refer to the transparent IE buffer: Macro Description acumessage_tsp_ie_list_size¹ Size of transparent IE buffer, in bytes. Note: When calculating this value, do NOT include a null terminator. acumessage_a_tsp_ie_list Pointer to transparent IE buffer. Note: Do NOT include null terminator in this string. ¹ acumessage is a standard ACU message (e.g. ACU_CONN_RQ). For example, Acu_conn_rq_tsp_ie_list_size
To use transparent IEs, the application must disable the stack's syntax checking mechanism. To do this, set the NS_IE_RELAY_BEHAVIOR bit in the ns_behavior sub-structure referenced in the ISDN_PROTOCOL_PARMS_ Q931CC structure passed to isdnStartProtocol. By default, this bit is 0. The following code fragment shows how to set this bit prior to calling isdnStartProtocol:

myStartProtocol() { struct ISDN_PROTOCOL_PARMS_Q931CC parms; ... memset(&parms,0,sizeof(ISDN_PROTOCOL_PARMS_Q931CC)); parms.size = sizeof(ISDN_PROTOCOL_PARMS_Q931CC); parms.services_list[0] = ACU_VOICE_SERVICE; /* other services may be added here */ parms.services_list[1] = ACU_NO_SERVICE; parms.ns_behaviour = NS_IE_RELAY_BEHAVIOR; ... isdnStartProtocol ( ctahd, ISDN_PROTOCOL_Q931CC, networkoperator, country, partner, SM->nai, &parms ); /* instead of NULL */ ... }

Macro	Description
acumessage`_tsp_ie_list_size`¹	Size of transparent IE buffer, in bytes. Note: When calculating this value, do NOT include a null terminator.
acumessage`_a_tsp_ie_list`	Pointer to transparent IE buffer. Note: Do NOT include null terminator in this string.

Transparent IE Formatting Rules

If the buffer contains more than 1 IE, the IEs must appear in the same order as they should appear in the Q.931 message. For example, the "channel id" (IE id = 0x18) cannot be followed by "bearer capability" (IE id = 0x04).
When the stack's syntax checking mechanism is disabled, the stack will NOT perform syntax checking on transparent IEs. It is the application's responsibility to build them according to the specifications for the variant the application will use.
The application should not use the transparent IE method and the macro method to access the same IE in the same ACU message. For example, if the application sets the macros for the called party number and includes the "Called party number" IE (IE id = 0x70) in the transparent IE buffer in the same ACU message, both IEs will be present in the final SETUP message.
Certain information elements are automatically generated by the stack in Q.931 messages. The stack does check to see if any of the transparent IEs sent to it correspond to these information elements. If it finds a transparent IE equivalent for an automatically generated information element, it uses the transparent IE instead.
The transparent IE buffer should not be null-terminated.
When calculating the size of a transparent IE buffer, do NOT include a null terminator.
The following is a list of IEs automatically generated by the stack:

Name

Applies to Variant

bc

All variants

llc

All variants except HKT, NTT, QSI, SWD

hlc

All variants except E10

cause

All variants

chan_id

All variants

Name	Applies to Variant
`bc`	All variants
`llc`	All variants except `HKT`, `NTT`, `QSI`, `SWD`
`hlc`	All variants except `E10`
`cause`	All variants
`chan_id`	All variants

Accessing and Reading a Q.931 Buffer

To read the raw data in an incoming Q.931 message, the application accesses the buffer containing the message using the following macros: Macro Description acumessage_q931_size¹ Size of Q.931 buffer, in bytes acumessage_a_q931 Pointer to Q.931 buffer ¹ acumessage is a standard ACU message (e.g. ACU_CONN_IN). For example, Acu_conn_in_q931
In order for this data to be available, the NS_BEHAVIOR_NIL bit must be set in the acu_behavior sub-structure referenced in the ISDN_PROTOCOL_PARMS_ Q931CC structure passed to isdnStartProtocol. By default, this bit is 0.
The following code fragment shows how to set this bit prior to calling isdnStartProtocol:

myStartProtocol() { struct ISDN_PROTOCOL_PARMS_Q931 parms; ... memset(&parms,0,sizeof(ISDN_PROTOCOL_PARMS_Q931CC)); parms.size = sizeof(ISDN_PROTOCOL_PARMS_Q931CC); parms.services_list[0] = ACU_VOICE_SERVICE; /* other services may be added here */ parms.services_list[1] = ACU_NO_SERVICE; parms.acu_behavior = ACU_SEND_Q931_BUFFER; ... isdnStartProtocol ( ctahd, ISDN_PROTOCOL_Q931CC, networkoperator, country, partner, SM->nai, &parms ); /* instead of NULL */ ... }
Note: The buffer is NOT null-terminated; thus it cannot be read by functions which expect null termination (such as strcpy).
The total amount of data (all buffers, including the raw Q.931 data buffer) that can be received in an ISDN message is MAX_ISDN_BUFFER_SIZE. (This value is defined in isdnparm.h.) If the size of incoming data would be greater than MAX_ISDN_BUFFER_SIZE, the raw Q.931 data buffer will be omitted.

Macro	Description
acumessage`_q931_size`¹	Size of Q.931 buffer, in bytes
acumessage`_a_q931`	Pointer to Q.931 buffer

(Page 1 of 1 in this chapter)

tech_support@nmss.com