3.1 Introduction

3.2 Supplementary Services in ACU Messages

3.3 Components of ACU Messages

3.3.1 Components of the ACU Data Buffer

3.3.2 Components of the Extended Data Area

3.4 Contents of Supplementary Service Extended Data Structures

3.4.1 The Operation ID

3.4.2 The Operation Type Identifier

3.5 Specifying Supplementary Service Extended Data Structures

3.5.1 Initializing the Extended Data Area

3.5.2 Filling Extended Data Structures For Supplementary Services

3.5.3 Supplementary Service Specification Code Sample

3.6 Retrieving Supplementary Service Information

3.6.1 Identifying Supplementary Service Extended Data Structures

3.6.2 Reading a Supplementary Service Extended Data Structure

3.6.3 Supplementary Service Retrieval Code Sample

3.7 Combining ACU Primitives and Supplementary Services Structures

3.7.1 Tightly Coupled Services

3.7.2 Loosely Coupled Services

3.7.3 Connection-Independent Services

3.8 Extended Data Structure Substructures

3.9 The acu_ss_reject Extended Data Structure

3.10 Specifying the Q.SIG Node Address

3.1 Introduction

This chapter:

• Explains how supplementary service information is included in ACU messages.

• Describes the components of supplementary service data structures.

• Describes how to include supplementary service data structures in an ACU message.

• Describes how to access supplementary service information in an incoming ACU message.

• Documents the acu_ss_reject structure.

3.2 Supplementary Services in ACU Messages

The supplementary services portion of the AG ISDN API is modeled as a protocol element separate from the call control protocol element. The call control element of a message is used to manage the basic call state, while the supplementary services element of a primitive manages the supplementary service states.

In order for these two elements to work together, but retain separation, the AG ISDN API basic call control buffer format allows for supplementary service information to be carried with the basic call control primitives, in separate structures. In most cases, the structures are attached to ACU_FACILITY_RQ or ACU_FACILITY_IN messages, as explicit control signaling for supplementary services. However, there are cases where extended data structures containing supplementary service information are attached to basic call control primitives such as ACU_CONN_RQ.

A single ACU message can carry multiple supplementary service structures. Each supplementary service structure contains information pertaining to a specific supplementary service.

3.3 Components of ACU Messages

To send a message to the AG ISDN protocol stack, the application builds two main structures, and then calls isdnSendMessage in the AG ISDN Messaging API library. The structures specified in the function call are:

• ISDN_MESSAGE. In this structure, the application specifies the message to be sent, using one of the message primitives documented in the AG ISDN Messaging API Developer's Reference Manual. Also specified is information identifying the context of the message, such as the connection ID, the NAI, and the SAPI.

• A data buffer, for messages that require additional data. The data (if any) differs for each message type. If supplementary service information is sent, it is included in this data.

The application assigns values to the fields in the ACU message structure using macros. These macros are defined in isdnacu.h. See your AG ISDN Messaging API Developer's Reference Manual for more information about message primitives and macros.

Figure 4 illustrates the content and meaning of each of the arguments sent in an isdnSendMessage function call:

Figure 4. isdnSendMessage Data Structures

When the ACU data structures reach the ISDN protocol stack, the stack rearranges the data into several Q.931 information elements (IEs), builds a complete Q.931 message with the IEs, and sends it to the network.

When an AG ISDN protocol stack message is received, an ISDNEVN_RCV_MESSAGE event occurs, using the standard CT Access event handling mechanism. buffer in the CT Access event structure is a pointer to an ISDN_PACKET structure. This structure contains:

• An ISDN_MESSAGE structure which contains the message, and other data.

• A buffer containing the message. If supplementary service information is received, it is included in this data.

Figure 5 illustrates the structure of this message packet:

Figure 5. Receiving Protocol Stack Messages

3.3.1 Components of the ACU Data Buffer

The ACU data buffer sent or received from the stack is made up of several blocks of information. These include:

• A fixed argument area. This is a C structure which is specific to the message primitive. It contains fixed length information required to process the primitive. It also contains offsets to fields in the variable length argument area (see below). All information in this area is specified using macros specific to the primitive. (See the AG ISDN Messaging API Developer's Reference Manual for more information.)

• A variable length argument area. This area contains variable length fields referenced by offsets in the fixed length structure. Data such as the called digit string are stored here. (See the AG ISDN Messaging API Developer's Reference Manual for more information.)

• An extended data area. This area can be used for a variety of purposes. This manual describes how this area is used to send and receive supplementary service information.

The following diagram illustrates the components of an ACU data buffer:

Figure 6. ACU Data Buffer Components

3.3.2 Components of the Extended Data Area

Within the extended data area, one or more supplementary service structures appear, one after the other. Each structure contains:

• An extended data structure header, identifying the structure as a "service" structure.

• A header identifying the type of service, and whether it is an invocation, rejection, or positive or negative acknowledgement.

• (Optional) A fixed length structure containing data specific to the supplementary service type and operation.
  The structures for each supplementary service can be found in isdnacu.h. Each structure is a standard C structure that can be accessed through a pointer cast to the appropriate type.

• (Optional) Variable length information pointed to in the fixed length structure.

In some cases, there is no additional data, so there is no fixed structure or variable length information beyond the header.

The following diagram illustrates the extended data area of an ACU message buffer:

Figure 7. Supplementary Service Data Structures

3.4 Contents of Supplementary Service Extended Data Structures

Each supplementary service structure contains:

• A unique operation ID. (see Section 3.4.1.) This information is stored in the service header.

• An operation type identifier. (see Section 3.4.2.) This information is stored in the service header.

• Data relevant to the operation. Each extended data structure is unique to the operation ID / operation type combination.

The structures for each valid combination can be found in isdnacu.h. Each structure is a standard C structure that can be accessed through a pointer cast to the appropriate type.

The following is a list of the extended data structures used to specify supplementary services in the extended data area of an ACU message. For a detailed description of each structure, see Appendix A.

Various substructures are used to contain data for fields in these structures. For more information, see Section 3.8.

Many fields in these structures are filled using predefined constants. For a list of the constants available for a field, see Appendix B.

Extended Data Structure	Purpose
acu_ss_act_divert_invoke	Request activation of Call Diversion service
acu_ss_act_divert_ret_error	Error in Call Diversion service activation request
acu_ss_act_divert_ret_result	Call Diversion service activation request successful
acu_ss_activate_deflect_invoke	Request activation of Call Deflection service
acu_ss_activate_deflect_ret_result	Call Deflection service activation request successful
acu_ss_aoc_inform_invoke	Information returned by Advice of Charge service
acu_ss_aoc_request_invoke	Request activation of Advice of Charge service
acu_ss_aoc_request_ret_error	Error in Advice of Charge service activation request
acu_ss_aoc_request_ret_result	Advice of Charge service activation request successful
acu_ss_bridge_calls_invoke	Request invocation of Bridge Calls service
acu_ss_bridge_calls_ ret_result	Bridge Calls service invocation successful
acu_ss_deact_divert_invoke	Request deactivation of Call Diversion service
acu_ss_deact_divert_ret_error	Error in Call Diversion service deactivation request
acu_ss_deact_divert_ret_result	Call Diversion service deactivation request successful
acu_ss_deactivate_deflect_invoke	Request deactivation of Call Deflection service
acu_ss_deactivate_deflect_ret_result	Call Deflection service deactivation request successful
acu_ss_deflect_invoke	Request to invoke Call Deflection for a call
acu_ss_deflect_ret_error	Error in Call Deflection attempt
acu_ss_deflect_ret_result	Successful Call Deflection attempt
acu_ss_divert_invoke	Request to forward a call (Call Diversion)
acu_ss_divert_ret_error	Successful Call Diversion
acu_ss_divert_ret_result	Error in Call Diversion attempt
acu_ss_enquire_divert_invoke	Attempt to invoke Enquire Diversion (enquire the network for users' Call Diversion service status)
acu_ss_enquire_divert_ret_error	Error in Enquire Diversion invocation
acu_ss_enquire_divert_ret_result	Successful invocation of Enquire Diversion service
acu_ss_hold_invoke	Invoke Call Hold service
acu_ss_hold_ret_result	Successful Call Hold (call is on hold)
acu_ss_notify_diversion_invoke	Invoke Notify Diversion service
acu_ss_notify_diversion_ret_result	Successful Notify Diversion
acu_ss_notify_hold_invoke	Invoke Notify Hold service
acu_ss_notify_retrieve_invoke	Invoke Notify Retrieve service
acu_ss_notify_transfer_invoke	Invoke Notify Transfer service
acu_ss_notify_transfer_ret_result	Successful Notify Transfer invocation
acu_ss_reject	Generic rejection message (see Section 3.9 )
acu_ss_reminder_diversion_invoke	Invoke Remind Diversion service
acu_ss_retrieve_invoke	Invoke Call Retrieve service
acu_ss_retrieve_ret_result	Successful Call Retrieve service invocation
acu_ss_transfer_invoke	Invoke Explicit Call Transfer for a call
acu_ss_transfer_ret_err	Error in Explicit Call Transfer
acu_ss_transfer_ret_result	Successful Explicit Call Transfer

3.4.1 The Operation ID

An operation ID is included in each supplementary service operation call. The ID indicates which supplementary service operation the structure pertains to.

Note: Identification supplementary services (CLIP, CONP, COLP, COLR, CONP and CLIR) do not have operation IDs. They are accessed using fields in the basic call control primitives. (See Chapter 9.)

The following is a list of valid operation IDs:

Supplementary Service Operation	Operation ID	Documented In
Invoke Bridge Calls	ACU_OP_ID_BRIDGE_CALLS	Chapter 4
Invoke Call Hold	ACU_OP_ID_HOLD	Chapter 5
Invoke Call Retrieve	ACU_OP_ID_RETRIEVE	Chapter 5
Notify Hold	ACU_OP_ID_NOTIFY_HOLD	Chapter 5
Notify Retrieve	ACU_OP_ID_NOTIFY_RETRIEVE	Chapter 5
Explicit Call Transfer	ACU_OP_ID_TRANSFER	Chapter 6
Notify Transfer	ACU_OP_ID_NOTIFY_TRANSFER	Chapter 6
Invoke Call Diversion	ACU_OP_ID_DIVERSION	Chapter 7
Activate Diversion	ACU_OP_ID_ACTIVATE_DIVERSION	Chapter 7
Deactivate Diversion	ACU_OP_ID_DEACTIVATE_DIVERSION	Chapter 7
Enquire Diversion	ACU_OP_ID_ENQUIRE_DIVERSION	Chapter 7
Remind Diversion	ACU_OP_ID_REMIND_DIVERSION	Chapter 7
Notify Diversion	ACU_OP_ID_NOTIFY_DIVERSION	Chapter 7
Invoke Call Deflection	ACU_OP_ID_DEFLECTION	Chapter 7
Activate Deflection	ACU_OP_ID_ACTIVATE_DEFLECTION	Chapter 7
Deactivate Deflection	ACU_OP_ID_DEACTIVATE_DEFLECTION	Chapter 7
Advice of Charge Request	ACU_OP_ID_AOC_REQUEST	Chapter 8
Advice of Charge Inform	ACU_OP_ID_AOC_INFORM	Chapter 8
Calling Name Identification Presentation (CNIP)	None.	Chapter 9
Connected Name Identifi- cation Presentation (CONP)	None.	Chapter 9
Calling Line Identification Presentation (CLIP)	None.	Chapter 9
Calling Line Identification Restriction (CLIR)	None.	Chapter 9
Connected Line Identification Presentation (COLP)	None.	Chapter 9
Connected Line Identification Restriction (COLR)	None.	Chapter 9

3.4.2 The Operation Type Identifier

An operation type identifier (optype) is included in each supplementary service operation call. The optype indicates what the supplementary service message means: why the message is being sent or received.

There are four valid operation types:

Operation Type	Meaning
ACU_OP_TYPE_INVOKE	The message is a request to invoke the supplementary service operation.
ACU_OP_TYPE_REJECT	The message indicates rejection of a request to invoke the operation. (See Section 3.9.)
Return Result (ACU_OP_TYPE_RETRES)	The message indicates successful completion of the operation.
Return Error (ACU_OP_TYPE_RETERR)	The message indicates unsuccessful completion of the operation.

3.5 Specifying Supplementary Service Extended Data Structures

To specify supplementary services, the application performs the following tasks:

1. It finds the beginning of the extended data area of the ACU message buffer.

2. In this area, it fills the structure for a supplementary service.

3. It finds the end of the structure just filled, adds another supplementary service substructure if necessary, and so on.

Most of these tasks are performed using specific macros and pointers. These are listed in the following sections.

3.5.1 Initializing the Extended Data Area

To begin specifying supplementary services, the application finds the end of the fixed and variable-length argument areas of the ACU message buffer, and sets a specific pointer there. The following table lists the pointers and macros used for these tasks:

Macro	Description
Acu_ext_descr_offset	Must be sent to indicate the beginning of the extended data area of the ACU message buffer. Assumes that a pointer, p_data, points to the first data character of the ACU message buffer.
Acu_xxxx_yy_start_ext_data	Indicates the offset to the first byte of the extended data area for message xxxx_yy. xxxx_yy is the name of an ACU message primitive minus the ACU_ prefix, in lowercase: conn_rq, facility_rq, etc.: Acu_facility_rq_start_ext_data
p_ext_data	Pointer to the beginning of the extended data structure currently being filled.

To initialize the extended data area:

1. The application completes the construction of the fixed and variable length argument areas of the ACU data buffer.
   The AG ISDN Messaging API Developer's Reference Manual describes how to do this.
   Note: The extended data area can be filled only when the rest of the ACU data buffer has been completed. Note: If you are building a Q.SIG application, the PINX node address is specified in your initial call to isdnStartProtocol. For more information, see Section 3.10.
2. The application declares the p_ext_data pointer. This pointer will indicate the beginning of the extended data structure currently being filled.

         unsigned char *p_ext_data;
   
   

3. If the supplementary service specification is to be sent with an ACU_FACILITY_RQ primitive, the application sets the Acu_facility_code macro to ACU_FAC_EXT_SERVICE to indicate that the extended data area is to be used.

         Acu_facility_code = ACU_FAC_EXT_SERVICE;
   
   

   This macro need not be set if any other ACU primitive is used.

4. The application sets the macro, Acu_ext_descr_offset, to indicate the beginning of the extended data area of the buffer. Each fixed data structure contains a macro that specifies the start of the extended data area.

         Acu_ext_descr_offset = Acu_facility_rq_start_ext_data;
   
   

   Note: These macros assume that a pointer, p_data, points to the first character of the buffer.

When these tasks are complete, the application can begin filling extended data structures and adding them to this area, one after the other. See Section 3.5.2.

3.5.2 Filling Extended Data Structures For Supplementary Services

To fill in an extended data structure for a supplementary service, the application first fills in the structure's service header, identifying the structure as a supplementary service structure, and specifying the type and operation of the service. It then fills the data structure for the service.

If additional data structures are required (for example, the application is specifying more than one supplementary service in the message), the pointer p_ext_data is set to the end of the structure just filled, and a new one is added. The macro Acu_ext_ss_build_end facilitates this procedure.

The following table lists the macros used for these tasks:

Macro	Description
Acu_ext_ss_build_begin(opid, optype)	Initializes a new supplementary service data structure. Sets p_ext_data to the beginning of the extended data structure, and stores the service operation type and id in the service structure header. opid is one of the operation ids listed in Section 3.4.1. optype is one of the operation type identifiers listed in Section 3.4.2.
Acu_ext_ss_build_end (p_end)	Called to indicate that building of an extended data structure is complete. p_end is a pointer to the byte after the last byte of the current extended data structure. If this structure includes variable-length data, p_end points to the first byte after the last data element. This macro calculates the length of the extended data area and of the new supplementary service structure and stores these values in the header. It also counts the number of supplementary service structures in this specification, and stores this value in the header.

To fill an extended data structure for a supplementary service:

1. The application calls the macro Acu_ext_ss_build_begin(opid, optype), to initialize a new supplementary service data structure.

2. opid is one of the operation IDs listed in Section 3.4.1.

3. optype is one of the operation type identifiers listed in Section 3.4.2.

         Acu_ext_ss_build_begin(ACU_OP_ID_DEFLECTION,ACU_OP_TYPE_INVOKE);
   
   

   The macro sets p_ext_data to the beginning of the extended data structure, and stores the service operation type and ID in the service structure header.

4. The application next sets a pointer to the appropriate data structure, so it equals p_ext_data.
   For example, for a Call Deflection invocation operation, the application would use the acu_ss_deflect_invoke data structure (defined in isdnacu.h):

         struct acu_ss_deflect_invoke
         {
         struct acu_ext_hdr        ext_hdr;           /*Extension header     */
         struct acu_ss_hdr         ss_hdr;            /*Supp. services header*/
         struct acu_address        deflect_to;        /*No. to direct call to*/
         struct acu_ss_association charge_association;/*Optional, used when  */
         };                                  /*AOC-E service has been invoked*/
                                       
   

   The following line shows how the application would set a pointer to this data structure:

         DeflectInvoke = (struct acu_ss_deflect_invoke *)p_ext_data;
   
   

   Note: If any optional strings are added, p_end must be adjusted for that string length.
5. The application now fills the extended data structure for the service.
   The extended data structure for each operation ID / operation type combination is listed in Section 3.4.

6. The application calculates the end of the supplementary services data structure.

         p_end += sizeof(struct acu_ss_deflect_invoke);
   
   

7. Lastly, the application calls Acu_ext_ss_build_end to indicate that the data structure is built:

         Acu_ext_ss_build_end (p_end);
   
   

   p_end is a pointer to the byte after the last byte of the current extended data structure. If this structure includes variable-length data, p_end points to the first byte after the last data element.
   This macro calculates the length of the extended data area and of the new supplementary service structure and stores these values in the header. It also counts the number of supplementary service structures in this specification, and stores this value in the header.

8. If there are additional supplementary service data structures to be added, steps 1 through 5 are repeated for each one.

3.5.3 Supplementary Service Specification Code Sample

The following code fragment shows how to create a supplementary service specification:

char *number;
unsigned char *p_end;
unsigned char *p_ext_data;
unsigned char JoinedConnID;
struct acu_facility *p_data;
struct acu_ss_notify_transfer_invoke *NotifyTransfer;

/*  Fill in the fixed portion of the facility message */
p_data = (struct acu_facility *)MsgBuffer;     /* Initialize p_data */

/*  First zero out the entire buffer */
memset(p_data, OFF, ISDN_BUFFER_DATA_LGTH);     /* Zero the structure */

/*  Tell the stack we are using supplementary services. Needed only if */
/*  supp. service is sent in ACU_FACILITY_RQ.  */
Acu_facility_code = ACU_FAC_EXT_SERVICE;     /* Supp. service */

/*  There is no more to do in the fixed structure except fill in header */
Acu_ext_descr_offset = Acu_facility_start_ext_data;

/*  Start supplementary service extended data structure, to invoke */
/*  Notify Transfer supplementary service */
Acu_ext_ss_build_begin(ACU_OP_ID_NOTIFY_TRANSFER,ACU_OP_TYPE_INVOKE);

/*  Set the structure pointer... */
NotifyTransfer = (struct acu_ss_notify_transfer_invoke *)p_ext_data;

/*  Calculate the address of where the data will go... */
p_end += sizeof(struct acu_ss_notify_transfer_invoke);

/*  FILL IN THE EXTENDED DATA STRUCTURE... */

/*  Some data fields follow */
NotifyTransfer->charge_id.invoke = 0;
NotifyTransfer->call_status = ACU_SS_CALL_STATUS_ANSWERED;
NotifyTransfer->end_designation = ACU_SS_END_DESIGNATION_PRIMARY;

/*  Redirecting number information */
NotifyTransfer->redir_nb.invoke = 1;
NotifyTransfer->redir_nb.presentation_restricted = 0;
NotifyTransfer->redir_nb.number_plan = ACU_SS_NUMBER_PLAN_PRIVATE_LEVEL_1_REGIONAL;
NotifyTransfer->redir_nb.screen_ind = ACU_SS_SCREEN_USER_PROV_VERIFIED;

/*  Copy in a number to the data area */
number = "1234567";             /* Dummy data */

/*Calculate offset, store length, store the data, advance the pointer */
NotifyTransfer->redir_nb.offset =
         (unsigned char)(p_end - (unsigned char*)&NotifyTransfer->redir_nb);
NotifyTransfer->redir_nb.len = strlen(number);   /* Length of data */
strcpy((char *)p_end, number);           /* Copy extended data */
p_end += strlen(number);
NotifyTransfer->joined_conn_id.board = BoardNumber;
NotifyTransfer->joined_conn_id.nai =  NAI;
NotifyTransfer->joined_conn_id.conn_num =  JoinedConnID;

/*  Field not used in this direction... */
NotifyTransfer->response_rq = 0;

/*  No sub-address information. */
NotifyTransfer->redir_sub.invoke = 0;
NotifyTransfer->redir_sub.pad = 0;
NotifyTransfer->redir_sub.type = 0;
NotifyTransfer->redir_sub.odd_even_ind = 0;
NotifyTransfer->redir_sub.offset = 0;
NotifyTransfer->redir_sub.len = 0;

/* Finished with this supp. service */
Acu_ext_ss_build_end(p_end)

3.6 Retrieving Supplementary Service Information

To access supplementary service information, the application does the following:

1. It finds the beginning of the extended data area of the ACU message buffer, and determines whether there are any extended data structures in it.

2. If extended data structures are present, it reads the extended data structure header of the first extended data structure to determine if it is a supplementary service structure or not.

3. If the structure is a supplementary service structure, the application reads the operation type and ID in the service header to determine what data to expect.

4. It sets a pointer to the first byte of the data, and reads it in.

5. It reads the size of the structure from the extended data structure header, and moves the pointer.

6. It repeats steps 2 through 5 for each extended data structure in the ACU message buffer.

Most of these tasks are performed using specific macros and pointers. These are listed in the following table:

Macro	Description
Acu_ext_id	Identifies the type of an extended data structure in the structure's extended data structure header. ACU_EXT_SERVICE indicates a supplementary service data structure.
Acu_ext_ss_op_id	Identifies the operation ID of a supplementary service in the service header of the extended data structure specifying the service.
Acu_ext_ss_op_type	Identifies the operation type of a supplementary service in the service header of the extended data structure specifying the service.
Acu_ext_descr_nb	Indicates the number of extended data structures in the extended data area.
Acu_ext_descr_first_address	Indicates the address of the first extended data structure. Assumes that a pointer, p_data, points to the first data character of the ACU message buffer.
Acu_ext_lgth	Indicates the length of the data area of the current extended data structure (the fixed-length area plus the variable-length area, if any).

3.6.1 Identifying Supplementary Service Extended Data Structures

To identify supplementary service extended data structures in the ACU message buffer, the application:

1. Checks the macro Acu_ext_descr_nb to determine how many (if any) extended data structures there are in the buffer.

2. Sets p_ext_data to the first data character of the extended data structure buffer.

         p_ext_data = Acu_ext_descr_first_address;
   
   

3. Determines whether or not an extended data structure is a supplementary service structure, by checking the macro Acu_ext_id. Its value (stored in the extended data structure header of the structure) should be ACU_EXT_SERVICES.

3.6.2 Reading a Supplementary Service Extended Data Structure

To read a supplementary service extended data structure, the application:

1. Reads the values of Acu_ext_ss_op_type and Acu_ext_ss_op_id to determine the operation ID and type of the supplementary service data structure. This determines which data structure to expect.
   For example, if Acu_ext_op_id is ACU_OP_ID_NOTIFY_TRANSFER and Acu_ext_op_type is ACU_OP_TYPE_INVOKE, the data structure is acu_ss_notify_transfer_invoke.

2. Uses p_ext_data to pick up the address of the extended structure.

3. Reads the information in the structure.

4. Resets p_ext_data to the end of the structure:

         p_ext_data = Acu_ext_descr_next_address;
   
   

5. Repeats steps 1 through 4 Acu_ext_descr_nb times.

3.6.3 Supplementary Service Retrieval Code Sample

The following code fragment shows how to retrieve supplementary service information from an ACU message:

unsigned char *p_ext_data;
if (Acu_ext_descr_nb > 0)
  {
    p_ext_data = Acu_ext_descr_first_address;
    /* process extended parameters */
    for (i = Acu_ext_descr_nb; i > 0; i--) 
    {
      process_acu_ext_element (p_ext_data);
      p_ext_data = Acu_ext_descr_next_address;
    }
 }
 void process_acu_ext_element(unsigned char *p_ext_data)
  {
    if (Acu_ext_id == ACU_EXT_SERVICES)
    {
      /* We have a parameter containing a service structure*/
      ....
      ProcessAcuExtService (p_ext_data)
    } 
  }
  void ProcessAcuExtService(unsigned char *p_ext_data)
  {
      ushort op_id = Acu_ext_ss_op_id;
      ushort op_type = Acu_ext_ss_op_type;
      ulong event = (op_id << 16) + op_type;
      struct acu_ss_notify_transfer_invoke *Transfer;
      struct acu_ss_aoc_inform_invoke *AOC;
      switch(event)
      {
        case (ACU_OP_ID_NOTIFY_TRANSFER << 16) + ACU_OP_TYPE_INVOKE:
        {
         Transfer = (struct acu_ss_notify_transfer_invoke *)p_ext_data;
         ...
        }
        break;
        case (ACU_OP_ID_AOC_INFORM << 16) + ACU_OP_TYPE_INVOKE:
        {
         AOC = (struct acu_ss_aoc_inform_invoke *)p_ext_data;
         ...
        }
        break;
      }
  }

3.7 Combining ACU Primitives and Supplementary Services Structures

The relationship between the ACU primitive type and the supplementary service operation that is carried can be divided into one of the three categories:

• Tightly Coupled

• Loosely Coupled

• Connection-Independent

3.7.1 Tightly Coupled Services

Tightly coupled services and primitives require that the supplementary service operation identifier and operation type be associated with a specific ACU primitive. For example, invocation of the Advice of Charge Request supplementary service must always be done within an ACU_CONN_RQ primitive.

When a service is tightly coupled with an ACU primitive, the service description in this document will list the primitive to use. If the application sends the service request in the wrong primitive, then the stack will return ACU_OP_TYPE_REJECT with a local cause of ACU_SS_REJECT_LOCAL_INVALID_STATE in response.

3.7.2 Loosely Coupled Services

Loosely coupled services and primitives share the same connection ID. In other words, the service applies to the same connection as the basic primitive. However, these services can be carried in any type of basic primitive.

When a loosely coupled service structure must be sent over the interface, and a basic call control primitive is also being sent, then the two can be combined into a single buffer. If there is no basic call primitive, then the ACU_FACILITY_RQ/IN/CO primitive can be used as a "NULL" basic call message and the service structure can be attached to it. For example, invocation of the Advice of Charge Inform service can be carried in any of the basic call primitives (e.g. ACU_ALERTING_IN, ACU_CLEAR_IN), or it may be in an ACU_FACILITY_IN.

While it is true that the primitive and the service are loosely coupled, it is still possible that the call state may prohibit the successful invocation of the service. For example, the Explicit Call Transfer (ECT) service can not be invoked on an inbound call that has not been answered. However, the service request can be sent in the ACU_CONN_RS primitive or a subsequent ACU_FACILITY_IN primitive.

Most supplementary services are loosely coupled with the primitive that carries them. The application must not assume which primitive type will carry a loosely coupled service.

3.7.3 Connection-Independent Services

Connection-independent services are not associated with a call in any way. An example of a connection-independent service is the Activate Diversion supplementary service.

Because there is no connection number associated with this service, a different mechanism is used to allow the discrimination between connection-oriented and connection-independent signaling. The sapi field is used for this purpose.

The sapi field of a connection-oriented message (e.g. ACU_CONN_RQ) is set to ACU_SAPI. The sapi field of a connection-independent message is set to ACU_SAPI_MGT. The ACU_FACILITY_RQ/IN/CO are the only primitives used to carry connection-independent service structures.

When the application constructs a connection-independent service structure, it should attach it to an ACU_FACILITY_RQ and set the value of the sapi field to ACU_SAPI_MGT. The application's discrimination function must not use the connection ID field of the message when the sapi field indicates a connection-independent message.

3.8 Extended Data Structure Substructures

Various substructures (listed below) are referenced in the supplementary service extended data structures listed in Section 3.4. They are used to contain particular types of information in the extended data structures, such as address or subaddress information, etc.

Each of these structures contains an invoke field. The invoke field is used to indicate the presence or absence of useful data in the structure. If the field is set to ON, then the stack uses the information in the structure. Otherwise, the information in the structure is ignored. If the successful invocation of the service requires the inclusion of the parameter, and the invoke field is OFF, then the service request is rejected.

Some structures contain a reference to a string location and string length. The string location is specified using the offset field in the structure. This offset value is calculated from the address of the structure containing the offset field.

The len field in the structure contains the length of the data. If you null-terminate the field, the length field must not include the null terminator.

Note: Structures sent from the stack do not include null terminations.

Substructure	Description
acu_address	Specifies the full address and subaddress of a party.
acu_conn_id	Specifies the connection information of a party.
acu_party_name	Specifies the name information of a party.
acu_party_num	Specifies the presentation indicator, numbering plan, and screen indicator of a party.
acu_party_subaddress	Specifies the subaddress of a party.
acu_ss_association	Contains a charge ID and charged number, for tracking charging information on transferred or forwarded calls. See Section 8.3.4 and Section 8.3.5.
acu_ss_chan	Specifies the channel information for a party.

3.9 The acu_ss_reject Extended Data Structure

If a stack or network error occurs when an attempt is made to invoke or activate a service, the acu_ss_reject substructure is returned in an ACU indication or confirmation message (such as ACU_FACILITY_IN or ACU_CLEAR_CO). The service header to this structure contains:

• The operation ID of the supplementary service (e.g. ACU_OP_ID_CALL_DEFLECTION)

• OpType ACU_OP_TYPE_REJECT

The following is a listing of the acu_ss_reject extended data structure:

struct acu_ss_reject
{
  struct acu_ext_hdr ext_hdr;       /* Extension header                */
  struct acu_ss_hdr  ss_hdr;        /* Supp. services header           */
  uchar              local_cause;   /* From SS_REJECT_LOCAL_ constants */
  uchar              network_cause; /* From SS_REJECT_NETWORK_constants*/
  pad6
};

The local_cause and network_cause fields in this structure indicate the cause for the rejection. The possible values for these fields are listed in Appendix B.

3.10 Specifying the Q.SIG Node Address

If you are building a Q.SIG application using supplementary services, you must specify the address of the Q.SIG node when your application starts the stack. To do so, specify the address number and type in the ISDN_PROTOCOL_PARMS_Q931CC structure referenced in the isdnStartProtocol call. The following fields specify the address:

• qsig_source_type_of_nb

• qsig_source_party_nb_type

• qsig_source_addr

For more information about these fields (including a list of possible values), see your AG ISDN Messaging API Developer's Reference Manual.