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

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)

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 (shown below). 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).

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); 

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.

• NMSGR303_SUCCESS
• NMSGR303_NOT_INITIALIZED
  The NMS GR303 library was not initialized with NMS_GR303Initialize.
• NMSGR303_INVALID_PARMS
  One or more of the function arguments were invalid.
• NMSGR303_INTERNAL_FAILURE
  Internal failure. Refer to the trace log for more information.
• NMSGR303_ALREADY_INITIALIZED
  The specified interface already exists.

• None.

This function 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 reprovision the interface before restarting the interface (unless the application wants to change its configuration). To reprovision 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 reprovisioning the entire interface by invoking NMS_GR303ModifyChannelLocation.

Note: The NMS CG303 library is unaware of primary and backup HDLC channel assignments.

The information in the NMS_GR303_CHANNEL_LOCATION_T structure includes the following:

Parameter	Description
boardNb	Logical board number where an HDLC instance is located.
trunkNb	Logical trunk number associated with the HDLC instance.
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 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 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.

When defining a channel callback function, channel_event values can be defined as follows:

Event Name	Description
NMSGR303_EVENT_RX_SUCCESS	A new HDLC frame was received and is available inside databuffer. datasize is set to the frame size.
NMSGR303_EVENT_RX_ERROR	An internal HDLC receive error occurred, and no data is available (no buffer is attached).
NMSGR303_EVENT_RX_FIFO_OVERRUN	HDLC receive FIFO overrun, no data is available (no buffer is attached).
NMSGR303_EVENT_RX_ABORT	The HDLC received an ABORT sequence, no data is available (no buffer is attached).
NMSGR303_EVENT_RX_CRC_ERROR	The HDLC received a bad CRC for the receive frame, and no data is available (no buffer is attached).
NMSGR303_EVENT_RX_NON_ALIGNED_OCTET	The HDLC received a non-aligned frame (not integer size of received bytes). No data is available (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 (no buffer is attached).
NMSGR303_EVENT_RX_MAX_LENGTH_ VIOLATION	Not supported.
NMSGR303_EVENT_TX_SUCCESS	The frame was transmitted successfully (no buffer is attached).
NMSGR303_EVENT_TX_ERROR	Internal HDLC transmit error occurred (no buffer is attached).
NMSGR303_EVENT_TX_FIFO_ UNDERRUN	HDLC transmit FIFO underrun (no buffer is attached).
NMSGR303_EVENT_TX_FIFO_OVERRUN	HDLC transmit FIFO overrun (no buffer is attached).
NMSGR303_EVENT_TX_QUEUE_FULL	HDLC transmit internal send queue is full (no buffer is attached). This error indicates an abnormal send rate.

NMS_GR303DestroyInterface, NMS_GR303ModifyChannelLocation, NMS_GR303StartInterface, NMS_GR303StopInterface

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); 
 }
}