Customization Tools for Installation and Configuration for Windows: NCM

NCM_AllocateTimeslots( )

Description | Cautions | Example | Error Codes | See Also

Name:

NCMRetCode NCM_AllocateTimeslots(pDeviceName, iNumTimeSlots, eArbitrary, ePersistent, pnNumOfBlocks, pNCMTSBlock)

Inputs:

NCMDevice *pDeviceName

pointer to a third party device name

int iNumTimeSlots

number of time slots to be allocated

NCMTSRequestType eArbitrary

determines whether the time slots that are allocated will be determined by the system or specifically set by the user

NCMTSReserveType ePersistent

determines the time slot reservation type (transient, persistent or all)

int *pnNumOfBlocks

pointer to the actual number of time slot blocks that are allocated

NCM_TS_BLOCK_STRUCT *pNCMTSBlock

pointer to the block of time slots to be returned

Returns:

NCM_SUCCESS if success NCM error code if failure

Includes:

NCMApi.h

Mode:

synchronous

Description

The NCM_AllocateTimeslots( ) function is used to allocate TDM bus time slots for use by third party devices. Intel® Dialogic boards will not use time slots that are allocated for third party devices.

The function parameters are defined as follows:

Parameter

Description

pDeviceName pointer to the data structure containing the name of the third party device that will be associated with the allocated time slots. A device name for this parameter is optional. If you do not want to associate a specific third party device with the allocated time slots, set this parameter to NULL. If you are associating a specific third party device with the allocated time slots, then the device name must be the same name you used to add the third party device to the system configuration with the NCM_AddThirdPartyDevice( ) function.

iNumTimeSlots indicates the number of time slots to be allocated. This parameter is ignored if the eArbitrary parameter is set to NCM_TIMESLOT_SPECIFIC.

eArbitrary indicates whether the allocated time slots will be arbitrary or specific. Valid settings are as follows:

NCM_TIMESLOT_ARBITRARY - time slot numbers within the reserved block of allocated time slots is determined by the system software.
NCM_TIMESLOT_SPECIFIC - time slot numbers within the reserved block of allocated time slots is set by the user. The iNumTimeSlots parameter is ignored when this value is used.

ePersistent determines whether or not the allocated time slots will persist when the system is rebooted. Valid settings are as follows:

NCM_TIMESLOT_PERSISTENT - allocated time slot blocks will be retained each time the system is rebooted.
NCM_TIMESLOT_TRANSIENT - allocated time slots will be released after the system is rebooted.

pnNumOfBlocks pointer to the actual number of time slot blocks that are allocated by the function call. A value of 1 indicates that a single, continuous block of time slots will be allocated. A value of greater than 1 indicates that multiple blocks of time slots will be allocated.

pNCMTSBlock pointer to NCM_TS_BLOCK_STRUCT data structure containing a block of time slots that is returned by the function call

The following table summarizes the valid parameter combinations for the NCM_AllocateTimeslots( ) function:

pDeviceName

eArbitrary

ePersistent

Result

NULL NCM_TIMESLOT_ARBITRARY NCM_TIMESLOT_PERSISTENT time slot blocks are not associated with a specific device, determined by the system software and retained when the system is rebooted.

NULL NCM_TIMESLOT_SPECIFIC NCM_TIMESLOT_PERSISTENT time slot blocks are not associated with a specific device, determined by the user and retained when the system is rebooted.

NULL NCM_TIMESLOT_ARBITRARY NCM_TIMESLOT_TRANSIENT time slot blocks are not associated with a specific device, determined by the system software and released when the system is rebooted.

NULL NCM_TIMESLOT_SPECIFIC NCM_TIMESLOT_TRANSIENT time slot blocks are not associated with a specific device, determined by the user and released when the system is rebooted.

device name set NCM_TIMESLOT_ARBITRARY NCM_TIMESLOT_PERSISTENT time slot blocks are associated with a specific device, determined by the system software and retained when the system is rebooted.

device name set NCM_TIMESLOT_SPECIFIC NCM_TIMESLOT_PERSISTENT time slot blocks are associated with a specific device, determined by the user and retained when the system is rebooted.

device name set NCM_TIMESLOT_ARBITRARY NCM_TIMESLOT_TRANSIENT time slot blocks are associated with a specific device, determined by the system software and released when the system is rebooted.

device name set NCM_TIMESLOT_SPECIFIC NCM_TIMESLOT_TRANSIENT time slot blocks are associated with a specific device, determined by the user and released when the system is rebooted.

Cautions

You must set the pnNumOfBlocks parameter to at least one. Similarly, you must allocate at least one element for the pNCMTSBlock parameter.
If you are reserving more than one block of time slots, the number of reserved time slot blocks (set by the pnNumOfBlocks parameter) must match the number of reserved NCM_TS_BLOCK_STRUCT data structures (set by pNCMTSBlock parameter).
The function returns NCME_BUFFER_TOO_SMALL if the memory reserved for the pNCMTSBlock parameter is not enough and returns the actual number of blocks needed in pNumOfBlocks. In this case, the caller should reallocate sufficient memory for the pNCMTSBlock parameter. Then make a second call to the NCM_AllocateTimeslots( ) function.

Example
#include "NCMApi.h" 
int                   iBusNumber = 0;
NCM_TS_BLOCK_STRUCT   *lpTimeSlotBlock = NULL;
int                   iNumOfBlocks = 1;
int                   iNumofTimeslot = 512;
NCMRetCode            ncmRc = NCM_SUCCESS;
int                   i = 0;
int                   timeslot = 0;
NCMDevice             deviceName;
Char                  DeviceString[] = "ThirdPartyDevice-XYZ#1";
deviceName.name = (char *) DeviceString;
deviceName.next = NULL; 
/*example for arbitrary time slot allocation*/ 
do
{
   if (lpTimeSlotBlock)
      free(lpTimeSlotBlock); 
   lpTimeSlotBlock = (NCM_TS_BLOCK_STRUCT *)malloc
       (sizeof(TS_BLOC_STRUCT) * lNumOfBlocks);
   memset(lpTimeSlotBlock, 0, sizeof(TS_BLOCK_STRUCT); 
for (int i = 0; i < lNumOfBlocks; i++)
{
   lpTimeSlotBlock[i].version = NCM_TIMESLOT_VER_0100;
} 
   //call NCM API function
   ncmRc = NCM_AllocateTimeslots(&deviceName, iNumofTimeslot, NCM_TIMESLOT_ARBITRARY, NCM_TIMESLOT_TRANSIENT, lpTimeSlotBlock, &iNumOfBlocks);
}
while (ncmRc == NCME_BUFFER_TOO_SMALL) 
if (ncmRc == NCM_SUCCESS)
{
for (i=0; i < dwNumOfBlocks; i++)
{
   for (timeSlot = lpTimeSlotBlock[i].start_time_slot;
       timeSlot < lTimeSlotBlock[i].start_time_slot +
      lpTimeSlotBlock[i].number_of_time_slots; timeSlot++)
    { //timeSlot is an acutal value of a time slot
 //do something with timeSlot
    }
}} 
/*example for allocation of a set of user-defined time slots (10-310, 500-712)*/
iNumOfBlocks = 2; 
lpTimeSlotBlock = (NCM_TS_BLOCK_STRUCT *)malloc
       (sizeof(NCM_TS_BLOCK_STRUCT) *iNumOfBlocks);
lpTimeSlotBlock[0].version = NCM_TIMESLOT_VER_0100;
lpTimeSlotBlock[0].struct_size = sizeof(NCM_TS_BLOCK_STRUCT);
lpTimeSlotBlock[0].start_time_slot = 10;
lpTimeSlotBlock[0].number_of_time_slots = 300;
lpTimeSlotBlock[1].version = NCM_TIMESLOT_VER_0100;
lpTimeSlotBlock[1].struct_size = sizeof(NCM_TS_BLOCK_STRUCT);
lpTimeSlotBlock[1].start_time_slot = 500;
lpTimeSlotBlock[1].number_of_time_slots = 212; 
//call NCM API function
ncmRc = NCM_AllocateTimeslots(NULL, iNumofTimeslot, NCM_TIMESLOT_SPECIFIC, NCM_TIMESLOT_TRANSIENT, lpTimeSlotBlock, &iNumOfBlocks); 
if (ncmRc !=NCM_SUCCESS)
   /*process error*/ 
if (ncmRc == NCM_SUCCESS)
{
   /*print out the time slots in each block*/
   printf("For the request of %d time slots, %d block(s) of time slots have been
   allocated: \n", iNumofTimeslot, iNumOfBlocks);
   for (i=0; i < iNumOfBlocks; i++)
   {
      printf("Block %d: \n", i);
      for (timeslot = lpTimeSlotBlock[i].start_time_slot;
            + lpTimeSlotBlock[i].number_of_time_slots; timeslot ++)
      { /*timeSlot is an actual value of a time slot
            do something with timeslot */
           printf("%d", timeslot);
      }
       printf("\n");
     }
    } 
/*you might choose to keep the starting time slot number in this transaction to use it in releasing time slots. */ 
...
/*free the memory for time slot block after use*/
if (lpTimeSlotBlock)
      free(lpTimeSlotBlock); 
Error Codes

Equate

Returned When

NCME_BUFFER_TOO_SMALL buffer is of an insufficient size

NCME_INVALID_INPUTS invalid inputs

NCME_UNAVAILABLE_TIMESLOT requested time slot is not available

NCME_INVALID_THIRDPARTY_DEVICE specified third party device does not exist

See Also

NCM_DeallocateTimeslots( )

Name:	NCMRetCode NCM_AllocateTimeslots(pDeviceName, iNumTimeSlots, eArbitrary, ePersistent, pnNumOfBlocks, pNCMTSBlock)
Inputs:	NCMDevice *pDeviceName	pointer to a third party device name
	int iNumTimeSlots	number of time slots to be allocated
	NCMTSRequestType eArbitrary	determines whether the time slots that are allocated will be determined by the system or specifically set by the user
	NCMTSReserveType ePersistent	determines the time slot reservation type (transient, persistent or all)
	int *pnNumOfBlocks	pointer to the actual number of time slot blocks that are allocated
	NCM_TS_BLOCK_STRUCT *pNCMTSBlock	pointer to the block of time slots to be returned
Returns:	NCM_SUCCESS if success NCM error code if failure
Includes:	NCMApi.h
Mode:	synchronous

Parameter	Description
pDeviceName	pointer to the data structure containing the name of the third party device that will be associated with the allocated time slots. A device name for this parameter is optional. If you do not want to associate a specific third party device with the allocated time slots, set this parameter to NULL. If you are associating a specific third party device with the allocated time slots, then the device name must be the same name you used to add the third party device to the system configuration with the NCM_AddThirdPartyDevice( ) function.
iNumTimeSlots	indicates the number of time slots to be allocated. This parameter is ignored if the eArbitrary parameter is set to NCM_TIMESLOT_SPECIFIC.
eArbitrary	indicates whether the allocated time slots will be arbitrary or specific. Valid settings are as follows: NCM_TIMESLOT_ARBITRARY - time slot numbers within the reserved block of allocated time slots is determined by the system software. NCM_TIMESLOT_SPECIFIC - time slot numbers within the reserved block of allocated time slots is set by the user. The iNumTimeSlots parameter is ignored when this value is used.
ePersistent	determines whether or not the allocated time slots will persist when the system is rebooted. Valid settings are as follows: NCM_TIMESLOT_PERSISTENT - allocated time slot blocks will be retained each time the system is rebooted. NCM_TIMESLOT_TRANSIENT - allocated time slots will be released after the system is rebooted.
pnNumOfBlocks	pointer to the actual number of time slot blocks that are allocated by the function call. A value of 1 indicates that a single, continuous block of time slots will be allocated. A value of greater than 1 indicates that multiple blocks of time slots will be allocated.
pNCMTSBlock	pointer to NCM_TS_BLOCK_STRUCT data structure containing a block of time slots that is returned by the function call

pDeviceName	eArbitrary	ePersistent	Result
NULL	NCM_TIMESLOT_ARBITRARY	NCM_TIMESLOT_PERSISTENT	time slot blocks are not associated with a specific device, determined by the system software and retained when the system is rebooted.
NULL	NCM_TIMESLOT_SPECIFIC	NCM_TIMESLOT_PERSISTENT	time slot blocks are not associated with a specific device, determined by the user and retained when the system is rebooted.
NULL	NCM_TIMESLOT_ARBITRARY	NCM_TIMESLOT_TRANSIENT	time slot blocks are not associated with a specific device, determined by the system software and released when the system is rebooted.
NULL	NCM_TIMESLOT_SPECIFIC	NCM_TIMESLOT_TRANSIENT	time slot blocks are not associated with a specific device, determined by the user and released when the system is rebooted.
device name set	NCM_TIMESLOT_ARBITRARY	NCM_TIMESLOT_PERSISTENT	time slot blocks are associated with a specific device, determined by the system software and retained when the system is rebooted.
device name set	NCM_TIMESLOT_SPECIFIC	NCM_TIMESLOT_PERSISTENT	time slot blocks are associated with a specific device, determined by the user and retained when the system is rebooted.
device name set	NCM_TIMESLOT_ARBITRARY	NCM_TIMESLOT_TRANSIENT	time slot blocks are associated with a specific device, determined by the system software and released when the system is rebooted.
device name set	NCM_TIMESLOT_SPECIFIC	NCM_TIMESLOT_TRANSIENT	time slot blocks are associated with a specific device, determined by the user and released when the system is rebooted.

Equate	Returned When
NCME_BUFFER_TOO_SMALL	buffer is of an insufficient size
NCME_INVALID_INPUTS	invalid inputs
NCME_UNAVAILABLE_TIMESLOT	requested time slot is not available
NCME_INVALID_THIRDPARTY_DEVICE	specified third party device does not exist

Click here to contact Telecom Support Resources