NMS_GR303ProvisionInterface

Configures (provisions) the HDLC channels for the specified interface.

Prototype

NMS_GR303_RESULT_T NMS_GR303ProvisionInterface ( NMS_GR303_INTERFACE_ID_T interfaceId, DWORD num_channels, NMS_GR303_CHANNEL_LOCATION_T *channel_loc_array, NMS_GR303_CHANNEL_CALLBACK_T *channel_callback, void *channel_rx_buffer, DWORD channel_rx_buffersize)

Argument	Description
interfaceId	Interface ID to associate with the provisioned interface. The valid range for interface ID values is 0 - 256.
num_channels	Number of HDLC channels to provision (the maximum is 4).
channel_loc_array	Pointer to an array of NMS_GR303_CHANNEL_LOCATION_T structures. The size of the array is specified by the num_channels argument. Each value in the channel_loc_array defines an HDLC location. typedef union _NMS_GR303_CHANNEL_LOCATION_T { struct { DWORD boardNb; DWORD trunkNb; DWORD timeslotNb; } CG; } NMS_GR303_CHANNEL_LOCATION_T The application must fill in a location structure that corresponds to the board family it is using (this is defined when invoking NMS_GR303Initialize). See the Details section for field descriptions.
channel_callback	Pointer to an application provided callback function. The library invokes this callback whenever it must pass an event associated with a provisioned HDLC channel. The application should return from this function as soon as possible. The callback function is defined as follows: typedef void(NMS_GR303_CHANNEL_CALLBACK_T) (NMS_GR303_INTERFACE_ID_T interfaceId, NMS_GR303_CHANNEL_LOCATION_T channel_loc, NMS_GR303_CHANNEL_EVENT_T channel_event, void databuffer, DWORD datasize); See the Details section for field descriptions.
channel_rx_buffer	Pointer to an application-allocated memory buffer.
channel_rx_buffersize	Size of the user allocated buffer specified by channel_rx_buffer. The minimum requirement for channel_rx_buffersize is defined by the NMS_GR303_RX_BUFFER_SIZE parameter.

Return values

Return value	Description
NMSGR303_SUCCESS
NMSGR303_ALREADY_INITIALIZED	Specified interface already exists.
NMSGR303_INTERNAL_FAILURE	Internal failure. Refer to the trace log for more information.
NMSGR303_INVALID_PARMS	One or more of the function arguments are invalid.
NMSGR303_NOT_INITIALIZED	NMS GR303 library was not initialized with NMS_GR303Initialize.

Details

NMS_GR303ProvisionInterface creates, initializes, and resets the specified HDLC instances, and leaves them configured but disabled. By default, NMS_GR303ProvisionInterface sets the signaling mode for the HDLC channel timeslots to RAW (or non-CAS).

Applications should call NMS_GR303ProvisionInterface before calling NMS_GR303StartInterface. After the application stops an interface with NMS_GR303StopInterface, the application does not need to re-provision the interface before restarting the interface (unless the application wants to change its configuration). To re-provision an existing configuration, the application must first call NMS_GR303DestroyInterface to destroy the provisioned configuration. However, the application can add or delete HDLC channels without re-provisioning the entire interface by invoking NMS_GR303ModifyChannelLocation.

Note: The application does not need to specify primary and backup HDLC channel assignments to NMS GR303.

The NMS_GR303_CHANNEL_LOCATION_T structure includes the following information:

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 instance (as defined by NMS OAM).
timeslotNb	Physical timeslot number associated with the HDLC instance.

When defining the channel_callback function, the application specifies the following arguments:

Argument	Description
interfaceId	The interface ID upon which the HDLC channel is provisioned.
channel_loc	HDLC location structure.
channel_event	HDLC channel event value, as defined in the next table.
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 channel_rx_buffer and that the buffer can be overwritten.
datasize	Size of the data saved in the buffer. The size should be 0 if there is no data attached to the event.

The channel_event field of the channel_callback function can include the following events:

Event name	Description
NMSGR303_EVENT_RX_ABORT	The HDLC channel received an ABORT sequence. No data is available and no buffer is attached.
NMSGR303_EVENT_RX_BUFFER_OVERFLOW	An internal HDLC receive buffer overflow occurred. The HDLC received a frame of invalid length. No data is available and no buffer is attached. Not supported for CG 6100C or CG 6500C boards.
NMSGR303_EVENT_RX_CRC_ERROR	The HDLC channel received a bad CRC for the receive frame. No data is available and no buffer is attached.
NMSGR303_EVENT_RX_ERROR	An HDLC receive error was returned. No data is available and no buffer is attached.
NMSGR303_EVENT_RX_FIFO_OVERRUN	A FIFO overrun occurred. No data is available and no buffer is attached. Not supported for CG 6100C or CG 6500C boards.
NMSGR303_EVENT_RX_MAX_LENGTH_VIOLATION	Not supported.
NMSGR303_EVENT_RX_NON_ALIGNED_OCTET	The HDLC channel received an incomplete frame. No data is available and no buffer is attached. Not supported for CG 6100C or CG 6500C boards.
NMSGR303_EVENT_RX_SUCCESS	A new HDLC frame was received and is available inside databuffer. datasize is set to the frame size.
NMSGR303_EVENT_TX_ERROR	An internal HDLC transmit error occurred (no buffer is attached).
NMSGR303_EVENT_TX_FIFO_OVERRUN	An HDLC transmit FIFO overrun occurred. No buffer is attached. Not supported for CG 6100C or CG 6500C boards.
NMSGR303_EVENT_TX_FIFO_UNDERRUN	An HDLC transmit FIFO underrun occurred. No buffer is attached. Not supported for CG 6100C or CG 6500C boards.
NMSGR303_EVENT_TX_QUEUE_FULL	The HDLC transmit internal send queue is full. No buffer is attached. This indicates an abnormal send rate.

Example

void  ProvisionInterface( void )
{
    NMS_INTERFACE         NewInterface = {0};
    NMS_GR303_RESULT_T    NmsResult;
    char                  Selection;

    printf("NMS_GR303ProvisionInterface:\n");

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

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

    /* Configure 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_GR303_CHANNEL_LOCATIONS);

    NmsResult = NMS_GR303ProvisionInterface (
                    NewInterface.InterfaceId,
                    NewInterface.NumChannels,
                    NewInterface.NMS_Channels,
                    ChannelCallBackFunction,
                  NewInterface.ChannelRxBuffer,
                    NewInterface.ChannelRxBufferSize);
    Result=%s\n",PRINT_RESULT(NmsResult));

    if( NMSGR303_SUCCESS != NmsResult )
    {
         /* Discard bad interface configuration */
         free(NewInterface.ChannelRxBuffer);
     }
}