NMS_V5ProvisionInterface

Configures the HDLC channels and E1 links for an active variant on the specified interface.

Prototype

NMS_V5_RESULT_T NMS_V5ProvisionInterface ( NMS_V5_INTERFACE_ID_T interfaceId DWORD num_e1s NMS_V5_E1_LOCATION_T *e1_loc_array NMS_V5_E1_STATUS_CALLBACK_T *e1_status_callback DWORD numchannels NMS_V5_CHANNEL_LOCATION_T *channel_loc_array NMS_V5_CHANNEL_CALLBACK_T *channel_callback void *channel_rx_buffer DWORD channel_rx_buffersize)

Argument	Description
interfaceId	Interface ID. The valid range for interface IDs is 0 - 253.
num_e1s	Number of E1 links to provision (the maximum number is 16).
e1_loc_array	Pointer to an array of NMS_V5_E1_LOCATION_T structures where each structure defines the location of an E1 link. The size of the array is specified by the num_e1s value. typedef union _NMS_V5_E1_LOCATION_T { struct { DWORD boardNb; DWORD trunkNb; } CG; }NMS_V5_E1_LOCATION_T See the Details section for field descriptions.
e1_status_callback	Pointer to an application-defined E1 status callback function. The NMS V5 library calls this function every time it needs to pass an event for a provisioned E1 link to the application. The callback function is defined as follows: typedef void( *NMS_V5_E1_STATUS_CALLBACK_T ) (NMS_V5_INTERFACE_ID_T interfaceId, NMS_V5_E1_LOCATION_T channel_loc, NMS_V5_E1_STATUSMASK_T e1_status) ; See the Details section for field descriptions.
numchannels	Number of HDLC channels provisioned on the specified interface (the maximum is 48).
channel_loc_array	Pointer to an array of NMS_V5_CHANNEL_LOCATION_T structures. The size of the array is specified by num_channels. Each element of channel_loc_array defines the HDLC location: typedef union _NMS_V5_CHANNEL_LOCATION_T { struct { DWORD boardNb; DWORD trunkNb; DWORD timeslotNb; } CG; }NMS_V5_CHANNEL_LOCATION_T See the Details section for field descriptions.
channel_callback	Pointer to an application-defined callback function. The library invokes the callback every time it needs to pass an event for a provisioned HDLC channel. The application must then return from the callback as soon as possible. The callback function is defined as follows: typedef void( NMS_V5_CHANNEL_CALLBACK_T ) ( NMS_V5_INTERFACE_ID_T interfaceId, NMS_V5_CHANNEL_LOCATION_T channel_loc, NMS_V5_CHANNEL_EVENT_T channel_event, void databuffer, DWORD datasize); See the Details section for field descriptions.
channel_rx_buffer	Pointer to application-allocated memory for passing HDLC channel event data.
channel_rx_buffersize	Size of the allocated buffer specified by channel_rx_buffer. The minimum requirement for the channel_rx_buffersize is defined by NMS_V5_RX_BUFFER_SIZE.

Return values

Return value	Description
NMSV5_SUCCESS
NMSV5_ALREADY_INITIALIZED	Specified interface is already initialized.
NMSV5_INTERNAL_FAILURE	Internal failure. Refer to the trace log for more information.
NMSV5_INVALID_PARMS	One or more of the function arguments are invalid.
NMSV5_NOT_INITIALIZED	NMS V5 library was not initialized with NMS_V5Initialize.

Details

NMS_V5ProvisionInterface provisions a new active interface. NMS_V5ProvisionInterface creates, initializes, and resets the specified HDLC channels and E1 links on the specified boards, leaving the channels configured but disabled.

To re-provision the configuration, the application must call NMS_V5DestroyInterface to destroy the existing configuration before calling NMS_V5ProvisionInterface. However, an application can add or delete E1 links associated with voice channels without re-provisioning the entire interface by invoking NMS_V5AddE1 and NMS_V5DeleteE1.

The e1_loc_array argument can include not only E1 links associated with HDLC channels, but also E1 links associated with voice channels. The NMS V5 library returns E1 events (through an application-defined e1_status callback) for all links in the list.

Each NMS_V5_E1_LOCATION_T structure includes the following values:

Field	Description
boardNb	Logical board number where an E1 link is located (as defined by NMS OAM).
trunkNb	Physical trunk number associated with the E1 link (as defined by NMS OAM).

When defining an E1 status callback, the application must specify the following arguments:

Argument	Description
interfaceId	Interface ID where the E1 link is provisioned.
e1_loc	E1 link location structure.
status_event	E1 link event bit mask.

The status_event field returned by the e1_status_callback function can combine any of the following values (which applications can extract with the & operator):

Value	Description
NMSV5_E1_LOS	Loss of signal.
NMSV5_E1_LOF	Loss of frame.
NMSV5_E1_AIS	Alarm indication signal.
NMSV5_E1_RAI	Remote alarm indication signal.
NMSV5_E1_CRC_BLOCK_ERR	CRC block error.
NMSV5_E1_CRC_BLOCK_INFO	Remote CRC block info (FEBE).
NMSV5_E1_NORMAL_FRAMES_0	Normal E1 frames, remote SA7 = 0.
NMSV5_E1_NORMAL_FRAMES_1	Normal E1 frames, remote SA7 = 1.

Note: The application should return from the e1_status callback as soon as possible.

The NMS_V5_CHANNEL_LOCATION_T structure includes the following fields:

Field	Description
boardNb	Logical board number where an HDLC instance is located (as defined by NMS OAM).
trunkNb	Logical trunk number associated with the HDLC channel (as defined by NMS OAM).
timeslotNb	Physical timeslot associated with the HDLC channel.

When defining the channel_callback function, the application must specify the following arguments:

Argument	Description
interfaceId	Interface ID upon which the HDLC channel is provisioned.
channel_loc	HDLC location structure.
channel_event	HDLC channel event value, as defined in the table that follows.
databuffer	A pointer to the buffer attached to the event. When the channel callback function returns, the library assumes that the application finished processing the transferred data buffer, and it can overwrite the buffer.
datasize	Size of the data passed in the buffer (0 if no data).

The channel_event field in the channel_callback function can include the following values:

Value	Description
NMSV5_EVENT_RX_ABORT	The HDLC channel received an ABORT sequence. No data is available and no buffer is returned.
NMSV5_EVENT_RX_BUFFER_OVERFLOW	An internal HDLC receive buffer overflow occurred. No data is available and no buffer is returned. Not supported for CG 6100C or CG 6500C boards.
NMSV5_EVENT_RX_CRC_ERROR	HDLC detected a bad CRC for a frame. No data is available and no buffer is returned.
NMSV5_EVENT_RX_ERROR	An internal HDLC receive error occurred. No data is available and no buffer is returned.
NMSV5_EVENT_RX_FIFO_OVERRUN	The HDLC channel received a FIFO overrun. No data is available and no buffer is returned. Not supported for CG 6100C or CG 6500C boards.
NMSV5_EVENT_RX_MAX_LENGTH_ VIOLATION	Not supported.
NMSV5_EVENT_RX_NON_ALIGNED_OCTET	The HDLC received an incomplete frame. No data is available and no buffer is returned. Not supported for CG 6100C or CG 6500C boards.
NMSV5_EVENT_RX_SUCCESS	A new HDLC frame was received and is available inside databuffer. datasize is set to the frame size.
NMSV5_EVENT_TX_ERROR	An internal HDLC transmit error occurred. No buffer is returned.
NMSV5_EVENT_TX_FIFO_OVERRUN	An HDLC channel FIFO overrun occurred. No buffer is returned. Not supported for CG 6100C or CG 6500C boards.
NMSV5_EVENT_TX_FIFO_UNDERRUN	An HDLC transmit FIFO underrun occurred. No buffer is returned. Not supported for CG 6100C or CG 6500C boards.
NMSV5_EVENT_TX_QUEUE_FULL	The HDLC transmit send queue is full. Under normal conditions this should never occur. No buffer is returned.

Example

void  ProvisionInterface( void )
{
    NMS_V5_INTERFACE   NewInterface = {0};
    NMS_V5_RESULT_T    NmsResult;
    BYTE               szMessage[NMS_V5_MIN_TRACE_BUF_SIZE] = {0};
    char               Selection;

    printf("NMS_V5ProvisionInterface:\n");

    /* Set parameters */
    promptdw_nodft("Enter InterfaceId", &NewInterface.InterfaceId);

    NewInterface.ChannelRxBufferSize = NMS_V5_RX_BUFFER_SIZE;
    NewInterface.ChannelRxBuffer = calloc(
                                 NewInterface.ChannelRxBufferSize, 1 );

    /* Configure E1 location parameters */
     do
       {
       Selection = 'y';
       promptchar("Add a new E1? (y/n)", &Selection );
          if(Selection == 'y')
          {
             GetE1LocationNMS(
               &NewInterface.NMS_E1s[NewInterface.NumE1s++] );
          }
       }
      while (Selection != 'n' && NewInterface.NumE1s <
               NMS_V5_E1_LOCATIONS);

    /* Add channel parameters */
    do
    {
        Selection = 'y';
        promptchar("Add a new channel ? (y/n)", &Selection );
        if(Selection == 'y')
        {

         GetChannelLocationNMS(
            &NewInterface.NMS_Channels[NewInterface.NumChannels++] );
        }
}
while (Selection != 'n' && NewInterface.NumChannels <
       NMS_V5_CHANNEL_LOCATIONS);

NmsResult = NMS_V5ProvisionInterface (NewInterface.InterfaceId,
                                 NewInterface.NumE1s,
                                 NewInterface.NMS_E1s,
                                 E1StatusCallBackFunction,
                                 NewInterface.NumChannels,
                                 NewInterface.NMS_Channels,
                                 ChannelCallBackFunction,
                                 NewInterface.ChannelRxBuffer,
                                 NewInterface.ChannelRxBufferSize);

printf ("NMS_V5ProvisionInterface:
       Result=%s\n",PRINT_RESULT(NmsResult));

NMS_V5ProvisionInterface

Prototype

Return values

Details

See also

Example