gc_OpenEx( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_OpenEx(linedevp, devicename, mode, usrattr)
Inputs:	LINEDEV *linedevp	pointer to returned line device
	char *devicename	pointer to ASCII string
	int mode	async or sync
	void *usrattr	pointer to user attribute
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	system controls and tools
Mode:	asynchronous or synchronous
Platform and Technology:	All† †See the Global Call Technology User's Guides for additional information.

Description

The gc_OpenEx( ) function opens a Global Call device and sets a user-defined attribute. The function also returns a unique line device ID (or handle) to identify the physical device or devices that carry the call. For example, a line device may represent a single network or time slot, or the grouping together of a time slot and a voice or media channel. All subsequent references to the opened device must be made using the line device ID. Both network board and channel (time slot) devices can be opened using the gc_OpenEx( ) function. A device may be opened only once and cannot be re-opened by the current process or by any other process until the device is closed.

After the successful return of the gc_OpenEx( ) function, the application must wait for a GCEV_UNBLOCKED event before proceeding with a call (make call or wait call) on the opened line device. When the GCEV_UNBLOCKED event is received, then the line is ready to accept or make calls. Note that the GCEV_UNBLOCKED event may be received before gc_OpenEx( ) returns; the application must be prepared to handle this.

The gc_OpenEx( ) function should be used in place of a gc_Open( ) function followed by a gc_SetUsrAttr( ) function. The gc_OpenEx( ) function includes all the functionality of the gc_Open( ) function plus the added feature of the usrattr parameter. The usrattr parameter points to a buffer where a user defined attribute is stored thus eliminating the need to call the gc_SetUsrAttr( ) function after calling a gc_Open( ) function.

Examples of using usrattr include using it as a pointer to a data structure associated with a line device or an index to an array. The data structure may contain user information such as the current call state or line device identification.

Parameter	Description
linedevp	points to unique number to be filled in by this function to identify a specific device
devicename	points to an ASCII string that defines the device(s) associated with the returned linedevp number. The devicename parameter specifies the device to be opened and the protocol to be used. The format used to define devicename is: <field1><field2>...<fieldn> These fields may be listed in any order. The field format is: :<key>_<field name> Valid keys and their appropriate field names are: P - protocol_name specifies the protocol to be used. See the appropriate Global Call Technology User's Guide for technology specific protocol information. The protocol_name field is not used on DM3 boards using T-1 or ISDN technology, because the protocol is determined at board initialization time and not when a Global Call device is opened. N - network_device_name specifies the board name and the time slot name (if needed) using the following naming convention: If the board is to be opened, the network_device_name is the board name. An example of the format is: dtiB<number of board> If a time slot is to be opened, both the board and time slot are specified. An example of the format is: dtiB<number of board>T<time slot number> See the appropriate Global Call Technology User's Guide for the correct network_device_name. V - voice_device_name specifies the voice board and channel. An example of the format is: dxxxB<virtual board number>C<channel number> Attachment to different types of DM3 voice devices is dependent on the protocol downloaded. For example, if one board has ISDN for protocols and another has T-1 CAS, the T-1 CAS network devices cannot be attached to the voice devices on the ISDN board. See the Global Call API Programming Guide for further information. M - media_device_name specifies the media board and channel. An example of the format is: ipmB<virtual board number>C<channel number> Not all technologies support voice or media devices. See the appropriate Global Call Technology User's Guide for the correct voice or media device names, if supported.
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution
usrattr	points to buffer where a user defined attribute is stored

Termination Events

GCEV_OPENEX

indicates successful completion of the gc_OpenEx( ) function, that is, the device was opened.

GCEV_OPENEX_FAIL

indicates that the gc_OpenEx( ) function failed and the device was not opened. A gc_Close( ) function must still be performed on the line device handle to free resources.

Cautions

• If a handler is enabled for the GCEV_UNBLOCKED event, then the linedevp parameter passed to the gc_OpenEx( ) function must be global so that any and all events can be processed.
• If a blocking alarm condition exists when opening a device, the application will not receive a GCEV_BLOCKED event since the application is already blocked.
• When using gc_OpenEx( ) in asynchronous mode to open a line device, an application must wait for the GCEV_OPENEX termination event before any other Global Call functions can be used on that line device.
• To handle error returns from the gc_OpenEx( ) function, use the Global Call error handling functions, gc_ErrorInfo( ) and gc_ResultInfo( ). Do not use the Linux errno variable to get Global Call error information. If you get either an EGC_DXOPEN or an EGC_DTOPEN error, use the error handling procedures recommended in the Standard Runtime Library API Programming Guide, Standard Runtime Library API Library Reference, and Digital Network Interface Software Reference for your operating system.
• See the Global Call Technology User's Guide for the network interface being used to determine required devicename components and features unique to the network interface.
• Once a voice, media, or network device is opened, you must perform a gc_Close( ) before calling gc_OpenEx( ) again. Calling gc_OpenEx( ) twice on the same device without first closing the device will not return an error, but any subsequent behavior of the resulting line device(s) is undefined.
• When using gc_OpenEx( ) in asynchronous mode, if a line device cannot be opened and the GCEV_OPENEX_FAIL event is received, the application must use gc_Close( ) on the line device handle to free resources.
• When using the North America Analog Protocol, the application must call the gc_LoadDxParm( ) function after calling gc_OpenEx( ). Failure to do so may lead to incorrect call progress information.
• A GCEV_UNBLOCKED event will be generated when opening a board device. A GCEV_BLOCKED event will also be generated if there are blocking alarms on the board, and the corresponding GCEV_UNBLOCKED event will be generated when the blocking alarms clear. The application must be prepared to handle these events.
• When using DM3 boards in a fixed routing configuration (see the "Working with Fixed Routing Configurations" section in the Global Call API Programming Guide), opening a network device also results in opening a voice device that is permanently bound to the network device. An application should not attempt to open the voice device that is already attached to an opened network device. If an application opens a voice device that is already attached to a network device, the application will receive a duplicate of each event on the voice device.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function to retrieve the reason for the error. If the GCEV_OPENEX_FAIL event is received, use the gc_ResultInfo( ) function to retrieve information about the event. See the "Error Handling" section in the Global Call API Programming Guide. All Global Call error codes are defined in the gcerr.h file. If the error returned is technology specific, see the technology-specific error header file(s) for the error definition (for example, ccerr.h or isdnerr.h file for the ISDN call control library).

Example

/* 
 * Standard Dialogic header(s)
 */
#include <srllib.h>
#include <dxxxlib.h>
#include <dtilib.h> 
/*
 * GlobalCall header(s)
 */
#include <gclib.h>
#include <gcerr.h> 
#define MAXCHAN   30               /* max. number of channels in system */ 
/*
 * Global variable
 */
char *program_name;               /* program name */ 
/*
 * Function prototype(s)
 */
int print_error(char *function);
int evt_hdlr(void);
int open_line_devices(void);
int close_line_devices(void); 
/*
 * Data structure which stores all information for each line
 */
static struct linebag {
    LINEDEV  ldev;                   /* GlobalCall API line device handle */
    CRN      crn;                    /* GlobalCall API call handle */
    int      blocked;                /* channel blocked/unblocked */
    int      networkh;               /* network handle */
    int      voiceh;                 /* voice handle */
} port[MAXCHAN+1]; 
/*
 * Main Program
 */ 
void main(int argc, char *argv[])
{
    int mode; 
    /* Set SRL mode */
    mode = SR_POLLMODE;
    if (sr_setparm(SRL_DEVICE, SR_MODEID, &mode) == -1) {
        printf( "Unable to set to Polled Mode");
        exit(1);
    } 
    /* Enable the event handler */
    if (sr_enbhdlr(EV_ANYDEV, EV_ANYEVT,
        (long (*) (void *))evt_hdlr) == -1) { 
        printf("sr_enbhdlr failed\n");
        exit(1);
    } 
    /* Start the library */
    if (gc_Start(NULL) != GC_SUCCESS) {
        /* process error return as shown */
        print_error("gc_Start");
    } 
    /* open the line devices */
    open_line_devices(); 
    sr_waitevt(50); 
    /* close the line devices */
    close_line_devices(); 
    /* Stop the library */
    if (gc_Stop() != GC_SUCCESS) {
        /* process error return as shown */
        print_error("gc_Stop");
    }
}  
/*
 * int print_error (char *function)
 *
 * INPUT: char *function - function name
 * RETURN: gc_error      - globalcall error number
 *
 */
int print_error(char *function)
{
    GC_INFO        gc_error_info; /* GlobalCall error information data */ 
    gc_ErrorInfo( &gc_error_info );
    printf ("Error: %s(), GC ErrorValue: 0x%hx - %s, CCLibID: %i - %s, 
            CC ErrorValue: 0x%lx - %s\n",
            function, gc_error_info.gcValue, gc_error_info.gcMsg, 
            gc_error_info.ccLibId, gc_error_info.ccLibName,
            gc_error_info.ccValue, gc_error_info.ccMsg);
    return (gc_error_info.gcValue);
} 
/*
 * int evt_hdlr (void)
 *
 * RETURN: 0             - function successful
 *         error         - GlobalCall error number
 *
 */
int evt_hdlr(void)
{
    struct channel    *pline;
    int               error;                       /* reason for failure of function */
    METAEVENT         metaevent; 
    if (gc_GetMetaEvent(&metaevent) != GC_SUCCESS) {
        /* process error return as shown */
        error = print_error("gc_GetMetaEvent");
        return(error);
    } 
      if (metaevent.flags & GCME_GC_EVENT) { 
        /* process GlobalCall events */ 
        if (gc_GetUsrAttr(metaevent.linedev, (void **)&pline) != GC_SUCCESS) {
           /* process error return as shown */
        error = print_error("gc_GetUsrAttr");
        return(error);
        } 
        switch (metaevent.evttype) {
           case GCEV_UNBLOCKED:
              printf("received GCEV_UNBLOCKED event on %s\n", ATDV_NAMEP(pline->networkh));
              pline->blocked = 0;
           break; 
           default:
              printf ("Unexpected GlobalCall event received\n");
           break;
        }
    }
    else {
        /* process other events */
    } 
       return 0;
} 
/*
 * int open_line_devices (void)
 *
 * RETURN: 0             - function successful
 *         error         - GlobalCall error number
 *
 */
int open_line_devices(void)
{
    char           devname[64];         /* argument to gc_OpenEx() function */
    int            vbnum = 0;           /* virtual board number (1-based) */
    int            vch = 0;             /* voice channel number (1-based) */
    int            ts;                  /* time slot number (1-based) */
    int            port_index;          /* index for 'port' */
    int            error;               /* reason for failure of function */ 
    /*
     * Construct device name parameter for OpenEx function and
     * Opened line devices for each time slot on DTIB1 using inbound
     * Argentina R2 protocol.
     */
    for (ts = 1,port_index = 1; ts <= MAXCHAN; ts++,port_index++) { 
        vbnum = (ts - 1) / 4 + 1;
        vch = ((ts - 1) % 4) + 1;
        sprintf (devname, ":N_dtiB1T%d:P_ar_r2_o:V_dxxxB%dC%d", ts, vbnum, vch);
        sr_hold();
        if (gc_OpenEx(&port[port_index].ldev, devname, EV_SYNC, 
                      (void *)&port[port_index]) != GC_SUCCESS) {
            /* process error return as shown */
            error = print_error("gc_OpenEx");
            sr_release();
            return(error);
        } 
        /* NOTE: The gc_SetUsrAttr() function is not required because
         *       the user attribute was set as a parameter in the 
         *       gc_OpenEx() function. 
         */ 
        if (gc_GetResourceH(port[port_index].ldev,
                &(port[port_index].networkh, GC_NETWORKDEVICE)) != GC_SUCCESS) {
            /* process error return as shown */
            error = print_error("gc_GetResourceH(GC_NETWORKDEVICE)");
            sr_release();
            return(error);
        } 
        if (gc_GetResourceH(port[port_index].ldev,
                &(port[port_index].voiceh), GC_VOICEDEVICE) != GC_SUCCESS) {
            /* process error return as shown */
            error = print_error("gc_GetVoiceH");
            sr_release();
            return(error);
        } 
        port[port_index].blocked = 1;  /* channel is blocked until unblocked */
                                       /* event is received. */
        sr_release();
    } 
    /*
     * Application is now ready to make a call or wait for a call.
     */
    return (0);
} 
/*
 * int close_line_devices (void)
 *
 * RETURN: 0             - function successful
 *         error         - GlobalCall error number
 *
 */
int close_line_devices(void)
{
    int port_index;    /* port index */
    int error;         /* reason for failure of function */ 
    for (port_index = 1; port_index <= MAXCHAN; port_index++) {
        if (gc_Close(port[port_index].ldev) != GC_SUCCESS) {
            /* process error return as shown */
            error = print_error("gc_Close");
            return (error);
        }
    }
    if (sr_dishdlr(EV_ANYDEV, EV_ANYEVT,
        (long (*) (void *))evt_hdlr) == -1) { 
        printf("sr_dishdlr failed\n");
        exit(1);
    }
    return 0;
} 

See Also

• gc_GetUsrAttr( )
• gc_SetUsrAttr( )

Click here to contact Telecom Support Resources