Version

Chapter 3

Alphabetical Function Reference

3.1 Introduction imgtReleaseBuffer 31

imgtSendMessage 33

imgtStart 35

imgtStop 38

3.1 Introduction

This chapter provides an alphabetically-ordered reference to the NMS ISDN Management API functions. A prototype of each function is shown with the function description and details of all arguments and return values. A typical function description includes:

Prototype

The prototype is shown followed by a listing of the function's arguments. Natural MicroSystems data types include:

· WORD
· DWORD
· INT16
· INT32
· BYTE

16 bit unsigned
32-bit unsigned
16-bit signed
32-bit signed
8-bit unsigned

If a function argument is a data structure, the complete data structure is defined. Refer to Chapter 4 for a description of all data structures and parameters.

Return Values

The return value for a function is either SUCCESS or an error code. For asynchronous functions, a return value of SUCCESS indicates the function was initiated; subsequent events indicate the status of the operation.
Refer to Appendix A for a listing of all errors returned by NMS ISDN Management API functions.

Events

If events are listed, the function is asynchronous and is complete when the DONE event is returned. If there are no events listed, the function is synchronous.
Additional information such as reason codes and return values may be provided in the value field of the event.
Refer to Appendix A for details for all NMS ISDN Management API events and reason codes.

Example

Example functions which start with Demo are samples taken from demonstration function libraries shipped with the product.
Example functions which start with my are excerpts taken from sample application programs shipped with the product.
The notation /* ... */ indicates additional code which is not shown.

imgtReleaseBuffer
Description
Releases a buffer after the application has finished processing it.
Prototype
DWORD imgtReleaseBuffer (CTAHD ctahd,
void *buffer)
ctahd Context handle returned by ctaCreateContext.
buffer Pointer to buffer to be released.
Return Values
SUCCESS
CTAERR_INVALID_HANDLE
The specified context handle is invalid.
IMGTERR_INVALID_BUFFER
buffer does not point to a valid buffer.
Events
None.
Details
This function sends an indication to the IMGT manager that the application has finished processing an event buffer (described by the CTA_EVENT buffer and size fields) and is returning that buffer to the IMGT service.
Note: The application must return every event buffer to the IMGT service as soon as possible, or the API will run out of buffers and stop passing events to the application.
Example
void MyEventHandler( CTAHD ctahd )
{
DWORD ret;
CTA_EVENT event;
char *errortext="";

while( 1 )
{
ret = ctaWaitEvent( ctahd, &event, 100 );

switch( event.id )
{
case CTAEVN_WAIT_TIMEOUT:
break;
case IMGTEVN_STARTED:
printf( "imgt started\n" );
break;
case IMGTEVN_STOPPED:
printf( "imgt stopped\n" );
break;
case IMGTEVN_RCV_MESSAGE:
/* process the buffer */
...
ret = imgtReleaseBuffer( ctahd, event.buffer );
if (ret != SUCCESS)
{
ctaGetText( ctahd, ret, (char *) errortext, 40);
printf( "imgtReleaseBuffer failure: %s\n",errortext );
exit( 1 );
}
break;
} /* end of switch */
}/* end of while */
}

imgtSendMessage
Description
Sends a message to the management manager with attached data.
Prototype
DWORD imgtSendMessage (CTAHD ctahd,
IMGT_MESSAGE *pmessage,
unsigned size,
void *pbuff)
ctahd Context handle returned by ctaCreateContext.
pmessage Pointer to IMGT_MESSAGE structure.
size Size of data block.
pbuff Pointer to the primitive-specific data structure (as specified in Section 4.2.3).

typedef struct IMGT_MESSAGE
{
BYTE nai; /* Network Access Identifier */
BYTE code; /* Primitive code */
WORD nfas_group; /* NFAS group number, only required for
Configurations with duplicate NAI values
on a board */
} IMGT_MESSAGE

Return Values
SUCCESS
CTAERR_BAD_ARGUMENT
This return value means any of the following:
· The message argument is NULL.
· The pbuff is NULL but size is non zero.
· The size of the data exceeds MAX_IMGT_BUFFER_SIZE.
CTAERR_INVALID_HANDLE
The specified context handle is invalid.
IMGTERR_IMGT_NOT_STARTED
A management session has not been initialized.
Events
IMGTEVN_SEND_MESSAGE
The event value field contains one of the following:
SUCCESS
IMGTERR_BUFFER_TOO_BIG
The size of the buffer is too large.
Details
See Section 4.2.3 for a list of valid messages and their associated buffer structures.
Example
void MySendOOS( CTAHD ctahd, unsigned char nai, unsigned char Bchannel )
{
IMGT_MESSAGE msg;
char pdata[MAX_IMGT_BUFFER_SIZE];
unsigned size;
struct imgt_service *psvc;
char *errortext="";

/* send SERVICE_RQ on nai to set Bchannel out of service */
msg.nai = nai;
msg.code = IMGT_SERVICE_RQ;

psvc = (struct imgt_service *) pdata;
psvc->type = PREFERENCE_BCHANNEL;
psvc->nai = msg.nai;
psvc->Bchannel = Bchannel;
psvc->status = OUT_OF_SERVICE;
size = sizeof( struct imgt_service );

ret = imgtSendMessage( ctahd, &msg, size, pdata );
if (ret != SUCCESS)
{
ctaGetText( ctahd, ret, (char *) errortext, 40);
printf( "imgtSendMessage failure: %s\n",errortext );
exit( 1 );
}
}
imgtStart
Description
Starts the IMGT service on a board.
Prototype
DWORD imgtStart (CTAHD ctahd,
unsigned nai,
IMGT_CONFIG *pconfig)
ctahd Context handle returned by ctaCreateContext.
nai Network access identifier of the ISDN channel being monitored.
pconfig Pointer to configuration structure:

typedef struct
{
DWORD size; /* size of structure */
DWORD imgt_mask; /* imgt event mask */
DWORD trap_mask; /* trap event mask (not used) */
DWORD mon_mask; /* monitor event mask (not used) */
WORD nfas_group; /* only required for configurations with
duplicate NAI values on a board */
BYTE pad[7]; /* pads */
} IMGT_CONFIG;

Return Values
SUCCESS
CTAERR_INVALID_HANDLE
The specified context handle is invalid.
IMGTERR_INVALID_CONFIG
The IMGT_CONFIG data structure contains invalid fields
(Invalid fields are those that are not currently implemented).
Events
IMGTEVN_STARTED
The event value field contains one of the following:
SUCCESS
The management manager has been properly configured. The user can now expect to receive only the events that have been configured.
IMGTERR_BAD_NAI
The network access identifier (NAI) in the message structure is not valid.
IMGTERR_NAI_IN_USE
The IMGT manager has already been started on this NAI.
IMGTERR_ISDN_NOT_STARTED
The ISDN stack has not been started for this NAI.
Details
The NMS ISDN protocol stack must be started before the IMGT service is started.
If the stack is stopped and started, IMGT messages remain as set, either enabled or disabled.
See Section 4.2.3 for a list of valid event masks.
For Natural Access 3.x, configured NAI values must be unique on a board. Also, a different structure is pointed to by pconfig:
typedef struct
{
DWORD size; /* size of structure */
DWORD imgt_mask; /* imgt event mask */
DWORD trap_mask; /* trap event mask (not used) */
DWORD mon_mask; /* monitor event mask (not used) */
} IMGT_CONFIG;

Example
void SetimgtConfiguration( CTAHD ctahd, unsigned char nai )
{
IMGT_CONFIG config;
DWORD ret;
char *errortext="";

memset(&config, 0, sizeof(IMGT_CONFIG));

/* get service and restart events */
config.imgt_mask = IMGT_SERVICE_MASK | IMGT_RESTART_MASK;

/* start receiving events on nai */
ret = imgtStart( ctahd, nai, &config );

if (ret != SUCCESS)
{
ctaGetText( ctahd, ret, (char *) errortext, 40);
printf( "imgtStart failure: %s\n",errortext );
exit( 1 );
}
/* wait for IMGTEVN_STARTED */
...
}

See Also
imgtStop
imgtStop
Description
Stops a management session initiated with imgtStart.
Prototype
DWORD imgtStop (CTAHD ctahd )
ctahd Context handle returned by ctaCreateContext.
Return Values
SUCCESS
CTAERR_INVALID_HANDLE
The specified context handle is invalid.
Events
IMGTEVN_STOPPED
The event value field can contain only the following:
SUCCESS
The management session has been stopped.
Example
void ResetimgtConfiguration( CTAHD ctahd )
{
DWORD ret;
char *errortext="";

/* stop receiving any events on the appropriate context */
ret = imgtStop( ctahd );

if (ret != SUCCESS)
{
ctaGetText( ctahd, ret, (char *) errortext, 40);
printf( "imgtStop failure: %s\n",errortext );
exit( 1 );
}
/* wait for IMGTEVN_STOPPED */
...

}
See Also
imgtStart

Prototype	The prototype is shown followed by a listing of the function's arguments. Natural MicroSystems data types include:
	· WORD · DWORD · INT16 · INT32 · BYTE	16 bit unsigned 32-bit unsigned 16-bit signed 32-bit signed 8-bit unsigned
	If a function argument is a data structure, the complete data structure is defined. Refer to Chapter 4 for a description of all data structures and parameters.
Return Values	The return value for a function is either SUCCESS or an error code. For asynchronous functions, a return value of SUCCESS indicates the function was initiated; subsequent events indicate the status of the operation. Refer to Appendix A for a listing of all errors returned by NMS ISDN Management API functions.
Events	If events are listed, the function is asynchronous and is complete when the DONE event is returned. If there are no events listed, the function is synchronous. Additional information such as reason codes and return values may be provided in the value field of the event. Refer to Appendix A for details for all NMS ISDN Management API events and reason codes.
Example	Example functions which start with `Demo` are samples taken from demonstration function libraries shipped with the product. Example functions which start with `my` are excerpts taken from sample application programs shipped with the product. The notation `/* ... */` indicates additional code which is not shown.

Version

Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com