isdnSendMessage

Sends a message to the ISDN stack, with optional attached data.

Prototype

DWORD isdnSendMessage ( CTAHD ctahd, ISDN_MESSAGE *message, void *pdata, unsigned size)

Argument

Description

ctahd

Context handle associated with a D channel, returned by ctaCreateContext.

message

Pointer to ISDN_MESSAGE structure, as follows:

typedef struct ISDN_MESSAGE
{
  nai_t nai;         /* Network access interface index                   */
  ent_id_t from_ent; /* Message source                                   */
  ent_id_t to_ent;   /* Message destination                              */
  sapi_t to_sapi;    /* Destination Service Access Point                 */
union {
      add_t conn_id; /* Connection identifier for the ACU layer          */
      add_t crv;     /* Call Reference value for NS layer. Not used.     */
      add_t ces;     /* Connection Endpoint suffix (DL layer upper 1/2)  */
      add_t tei;     /* Terminal Endpoint ID, DL layer lower 1/2 Not used*/
      add_t chani;   /* Physical layer channel identifier. Not used.     */
      } add;
  code_t code;       /* Primitive code unique only between 2 entities    */
  WORD inf0;         /* Information location 0                           */
  WORD inf1;         /* Information location 1                           */
  WORD inf2;         /* Information location 2                           */
  WORD inf3;         /* Information location 3                           */
  WORD inf4;         /* Information location 4                           */
  WORD data_size;    /* Size of data to follow                           */
  WORD nfas_group;   /* NFAS group number, used for configurations       */
                     /* with duplicate NAI values only                   */
  DWORD userid;      /* User ID                                          */
} ISDN_MESSAGE;

pdata

Pointer to the message data (if any). The data is specific to the type of message specified in ISDN_MESSAGE.

size

Size of data block referenced by pdata. size must match the data_size field in the ISDN_MESSAGE structure.


Return values

Return value

Description

SUCCESS

 

CTAERR_BAD_ARGUMENT

This return value means any of the following:

  • message argument is NULL.

  • pdata is NULL but size is non-zero.

  • data_size in the message does not match the size parameter.

  • Size of the data exceeds MAX_ISDN_BUFFER_SIZE.

CTAERR_INVALID_CTAHD

Context handle is invalid.


Events

Event name

Description

ISDNEVN_SEND_MESSAGE

The event value field contains one of the following reasons or an error code:

SUCCESS

ISDNERR_BAD_NAI

The network access identifier (NAI) in the message structure is not valid (the NAI must be less than MAX_NAI specified in isdnparm.h), or an nfas_group and NAI couple is not valid (if duplicate NAI values are defined).

ISDNERR_BUFFER_TOO_BIG

The size of the buffer is too large.


Details

This function sends a message with optional attached data to the ISDN subsystem. Any ISDN-specific command can be sent to any layer of the protocol stack using this function. The ISDN_MESSAGE structure contains the addressing information for the message.

The size field of the event contains the user ID for the message, as specified in the userid field in ISDN_MESSAGE. This value is sent to distinguish between multiple messages sent to the protocol stack. ISDN_USERID_ASYNC is reserved for events initiated by the protocol stack.

If multiple NAI values have not been defined, it is recommended to set nfas_group to 0.

See also

isdnReleaseBuffer

Example

DWORD sample_send_message (CTAHD ctahd, int mycode)
{
CTA_EVENT     event;
DWORD         ret;
ISDN_MESSAGE  imsg={0};
code_t        code;
unsigned char idata[MAX_ISDN_BUFFER_SIZE];
unsigned      datasize;

/*
** Protocol already started
*/
imsg.nai = 0;
imsg.nfas_group = 0
/*
** When using ACU, all messages should be directed
** to ENT_ACU and the ACU_SAPI within it.
** The from_ent field should always be ENT_APPLI.
*/
imsg.from_ent = ENT_APPLI;
imsg.to_ent   = ENT_CC;
imsg.to_sapi  = ACU_SAPI;

/*
** The connection ID is the logical connection number.
** For ACU, the lowest unused connection ID value must be used.
*/
imsg.add.conn_id = myGetLowestConnectionId();

/*
** Build the contents of the message for place call, release call, etc.
** This should fill the idata with the message contents and return the 
** used part of the data buffer in the datasize argument and the code for the 
** requested function (ACU_CONN_RQ, ACU_CLEAR_RQ, etc).
*/
myBuildMessage( mycode, idata, &datasize, &code);
imsg.datasize = datasize;
imsg.code     = code;

/*
** Add an ISDN-specific user ID to identify this message if it fails:
*/
imsg.userid = myGetNextMessageId();

ret = isdnSendMessage( ctahd, &imsg, idata, datasize);
if( ret != SUCCESS)
{
    ctaGetText(ctahd, ret, errortext, 40;
    printf("SEND_FAIL: %s mg id=%x\n", errortext, imsg.userid );
    return MY_ERROR_SEND_FAILED;
}
myWaitForEvent( ctahd, &event)
if( event.value != SUCCESS)
{
    ctaGetText(ctahd, event.value, errortext, 40);
    printf("SEND_FAIL: %s mg id=%x\n", errortext, imsg.userid );
    return MY_ERROR_SEND_FAILED;
}
...
}