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

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)

interfaceId Interface ID. The valid range for interface IDs is 0-253

num_e1s Number of E1 links to provision (the maximum is 16).

e1_loc_array Pointer to an array of NMS_V5_E1_LOCATION_T structures (shown below) where each 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

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

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

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

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.

• NMSV5_SUCCESS
• NMSV5_NOT_INITIALIZED
  The NMS V5 library was not initialized with NMS_V5Intialize.
• NMSV5_INVALID_PARMS
  One or more of the function arguments were invalid.
• NMSV5_INTERNAL_FAILURE
  Internal failure. Refer to the trace log for more information.
• NMSV5_ALREADY_INITIALIZED
  The specified interface is already initialized.

• None.

This function 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 reprovision 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 reprovisioning 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:

Parameter	Description
boardNb	Logical board number where an E1 like is located.
trunkNb	Physical trunk number associated with the E1 link.

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

Argument	Description
interfaceId	The 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):

Event Name	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.

NMS_V5_CHANNEL_LOCATION_T structure includes the following parameters:

Parameter	Description
boardNb	Logical board number where an HDLC instance is located.
trunkNb	Logical trunk number associated with the HDLC channel.
timeslotNb	Physical timeslot associated with the HDLC channel.

When defining the channel_callback function, the application must specify 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 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 returned in the channel_callback function can include the following:

Event Name	Description
NMSV5_EVENT_RX_SUCCESS	A new HDLC frame was received and is available inside databuffer. datasize is set to the frame size.
NMSV5_EVENT_RX_ERROR	An internal HDLC receive error occurred. No data is available and no buffer is returned.
NMSV5_EVENT_RX_FIFO_OVERRUN	HDLC receive FIFO overrun. No data is available and no buffer is returned.
NMSV5_EVENT_RX_ABORT	HDLC receive ABORT sequence. No data is available and no buffer is returned.
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_NON_ALIGNED_OCTET	The HDLC receive non-aligned frame. 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.
NMSV5_EVENT_RX_MAX_LENGTH_ VIOLATION	Not supported.
NMSV5_EVENT_TX_SUCCESS	Not supported.
NMSV5_EVENT_TX_ERROR	Internal HDLC transmit error occurred. No buffer is returned.
NMSV5_EVENT_TX_FIFO_UNDERRUN	HDLC transmit FIFO underrun. No buffer is returned.
NMSV5_EVENT_TX_FIFO_OVERRUN	HDLC transmit FIFO overrun. No buffer is returned.
NMSV5_EVENT_TX_QUEUE_FULL	HDLC transmit send queue is full. Under normal conditions this should never occur. No buffer is returned.

NMS_V5AddE1, NMS_V5DeleteE1, NMS_V5DestroyInterface, NMS_V5ProvisionStandByVariant, NMS_V5StartInterface

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