gc_GetMetaEvent( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_GetMetaEvent(metaeventp)
Inputs:	METAEVENT *metaeventp	pointer to METAEVENT data structure
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	system controls and tools
Mode:	synchronous
Platform and Technology:	All

Description

The gc_GetMetaEvent( ) function retrieves event information for the current SRL event that stores the Global Call and non-Global Call event information. This METAEVENT is a data structure that explicitly contains the information describing the SRL event to be returned to the Linux or Windows application. This data structure provides uniform information retrieval among call control libraries and across operating systems. See METAEVENT for more information.

You must call the gc_GetMetaEvent( ) function to retrieve any Global Call event information and any other event information if you are not sure of the event type. If the metaevent is a Global Call event, the GCME_GC_EVENT bit in the METAEVENT flags field will be set. The Global Call-related fields of the METAEVENT data structure contain valid data only when the GCME_GC_EVENT bit is set. Do not use these fields if the bit is not set.

The current SRL event information is not changed or altered by calling the gc_GetMetaEvent( ) function to retrieve event information. This function may be used as a convenience function to retrieve the event information for all SRL events. Whether the event is a Global Call event or any other SRL event, the SRL event information (for example, evtdatap, evttype) may be retrieved from the METAEVENT data structure instead of using SRL functions to retrieve this information.

Parameter	Description
metaeventp	points to the METAEVENT structure filled by this function

Termination Events

None

Cautions

• The gc_GetMetaEvent( ) function must be the first function called before processing any Global Call event.
• For Windows applications, when using the extended asynchronous model, the gc_GetMetaEventEx( ) function must be the first function called before processing any Global Call event. For all other Windows models, use the gc_GetMetaEvent( ) function.
• An application should call the gc_GetMetaEvt( ) function only once for a given event. Calling the function more than once will result in data corruption or an access violation.
• The event must be processed entirely in the same thread or all information about the event must be retrieved before processing the event in another thread.
• The gc_GetMetaEvent( ) and gc_GetMetaEventEx( ) functions should not be used in the same application.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function to retrieve the reason for the error. 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

The following code illustrates calling the gc_GetMetaEvent( ) function in response to receiving an event via the SRL.

    if(sr_waitevt(timeout) != -1) {     /* i.e. an event occurred */
        retcode = gc_GetMetaEvent(&metaevent);
        if (retcode <0) {
            /* get and process the error */
        } else {
            /* Continue with normal processing */
        }
    } 

OR

    handler(...)
    {
        retcode = gc_GetMetaEvent(&metaevent);
        if (retcode <0 ) {
            /* get and process the error */
        } else {
            /* Continue with normal processing */
        }
    } 

To retrieve and process information associated with an event, the following example code can be used. This code returns the event type, event data pointer, event length and event device associated with the event from either the handler or after a sr_waitevt( ) function call.

    retcode = gc_GetMetaEvent(&metaevent);
    if (retcode <0) {
          /* get and process error */
    } else {
          /* Can now access SRL information for any GlobalCall or 
             non-GlobalCall event using: */
          /* metaevent.evtdatap */
          /* metaevent.evtlen */
          /* metaevent.evtdev */
          /* metaevent.evttype */
       if (metaevent.flags & GCME_GC_EVENT) {
          /* process GlobalCall event here */
       } else {
          /* process non-GlobalCall event here */
       }
    } 

The following code illustrates retrieving event information from the METAEVENT structure while making a call:

#include <stdio.h>
#include <srllib.h>
#include <gclib.h>
#include <gcerr.h> 
#define MAXCHAN   30                 /* max. number of channels in system */
#define NULL_STATE 0
#define DIALING_STATE   1
#define ALERTING_STATE  2
#define CONNECTED_STATE 3 
/*
 * Data structure which stores all information for each line
 */ 
struct linebag {
   LINEDEV  ldev;                    /* network line device handle */
   CRN      crn;                     /* GlobalCall API call handle */
   int      state;                   /* state of first layer state machine */
} port[MAXCHAN+1]; 
struct linebag *pline;               /* pointer to access line device */ 
/*
 * Assume the following has been done:
 *    1. Opened line devices for each time slot on DTIB1.
 *    2. Application is in the NULL state
 * Examples are given in ASYNC mode
 * Error handling is not shown
 */ 
int makecall(int port_num, char *numberstr)
{
    GC_INFO        gc_error_info;    /* GlobalCall error information data */
    long           evttype;          /* type of event */ 
    /* Find info for this time slot, specified by 'port_num' */
    /* (Assumes port_num is valid) */ 
    pline = port + port_num; 
    if (gc_MakeCall(pline -> ldev, &pline -> crn, numberstr, NULL, 0, EV_ASYNC) != 
       GC_SUCCESS) {
      /* process error and return */
    }
    pline -> state = DIALING_STATE; 
    for (;;) {
       sr_waitevt(-1L);              /* wait forever */ 
       /* Get the next event */
       if (gc_GetMetaEvent(&metaevent) != GC_SUCCESS) {
          /* process error */
          gc_ErrorInfo( &gc_error_info );
          printf ("Error: gc_GetMetaEvent() on linedev: 0x%lx, GC ErrorValue: 0x%hx - %s, 
                CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
                metaevent.evtdev, 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);
       } 
       evttype = metaevent.evttype;
       if (metaevent.flags & GCME_GC_EVENT) {
          /* process GlobalCall event */
          switch (pline -> state) {
             case DIALING_STATE:
                switch (evttype) {
                   case GCEV_ALERTING:
                      pline -> state = ALERTING_STATE;
                      break;
                   case GCEV_CONNECTED:
                      pline -> state = CONNECTED_STATE;
                      /*
                       * Can now do voice functions, etc.
                       */
                      return(0);                 /* SUCCESS RETURN POINT */
                   default:
                      /* handle other events here */
                      break;
                }
                break; 
             case ALERTING_STATE:
                switch (evttype) {
                   case GCEV_CONNECTED:
                      pline -> state = CONNECTED_STATE;
                      /*
                       * Can now do voice functions, etc.
                       */
                      return(0);                 /* SUCCESS RETURN POINT */
                   default:
                      /* handle other events here */
                      break;
                }
                break;
          }
       } else {
          /* Process non-GlobalCall event */
       }
    }
} 

The following code illustrates retrieving event information from the METAEVENT structure while waiting for a call:

#include <stdio.h>
#include <srllib.h>
#include <gclib.h>
#include <gcerr.h> 
#define MAXCHAN   30                 /* max. number of channels in system */
#define NULL_STATE 0
#define CONNECTED_STATE 3
#define OFFERED_STATE   4
#define ACCEPTED_STATE  5 
/*
 * Data structure which stores all information for each line
 */ 
struct linebag {
   LINEDEV  ldev;                    /* network line device handle */
   CRN      crn;                     /* GlobalCall API call handle */
   int      state;                   /* state of first layer state machine */
} port[MAXCHAN+1]; 
struct linebag *pline;               /* pointer to access line device */ 
/*
 * Assume the following has been done:
 *    1. Opened line devices for each time slot on DTIB1.
 *    2. Application is in the NULL state
 *    3. A gc_WaitCall() has been successfully issued
 *
 * Examples are given in ASYNC mode
 * Error handling is not shown
 */ 
int waitcall(int port_num)
{
    GC_INFO        gc_error_info;    /* GlobalCall error information data */ 
    long           evttype;          /* type of event */ 
    /* Find info for this time slot, specified by 'port_num' */
    /* (Assumes port_num is valid) */
    pline = port + port_num; 
    for (;;) {
       sr_waitevt(-1L);              /* wait forever */ 
       /* Get the next event */
       if (gc_GetMetaEvent(&metaevent) != GC_SUCCESS) {
          /* process error return */
          gc_ErrorInfo( &gc_error_info );
          printf ("Error: gc_GetMetaEvent() on linedev: 0x%lx, GC ErrorValue: 0x%hx - %s, 
                CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
                metaevent.evtdev, 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); 
       } 
       evttype = metaevent.evttype;
       if (metaevent.flags & GCME_GC_EVENT) {
          /* process GlobalCall event */
          switch (pline -> state) {
             case NULL_STATE:
                switch (evttype) {
                   case GCEV_OFFERED:
                      pline -> state = OFFERED_STATE;
                      accept_call();
                      break;
                   default:
                      /* handle other events here */
                      break;
                }
                break; 
             case OFFERED_STATE:
                switch (evttype) {
                   case GCEV_ACCEPT:
                      pline -> state = ACCEPTED_STATE;
                      answer_call();
                      break;
                   default:
                      /* handle other events here */
                      break;
                }
                break;
             case ACCEPTED_STATE:
                switch (evttype) {
                   case GCEV_ANSWERED:
                      pline -> state = CONNECTED_STATE;
                      /*
                       * Can now do voice functions, etc.
                       */
                      return(0);                 /* SUCCESS RETURN POINT */
                   default:
                      /* handle other events here */
                      break;
                }
                break;
          }
       } else {
          /* Process non-GlobalCall event */
       }
    }
} 

See Also

• gc_GetLineDev( )
• gc_GetMetaEventEx( ) (Windows extended asynchronous model only)
• gc_ResultInfo( )
• gc_ResultValue( ) (deprecated)

Click here to contact Telecom Support Resources