gc_GetMetaEventEx( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_GetMetaEventEx(metaeventp, evt_handle)(Windows extended asynchronous model only)
Inputs:	METAEVENT *metaeventp	pointer to METAEVENT data structure
	unsigned long evt_handle	SRL event handle
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_GetMetaEventEx( ) function retrieves event information for an SRL event. The SRL event handle is specified in the evt_handle parameter.

The gc_GetMetaEventEx( ) function is used only in Windows applications that are running multithreads in the extended asynchronous model. The gc_GetMetaEventEx( ) function returns a metaevent, which contains the SRL event information of the specified event handle, to the application. If your application uses the sr_WaitevtEx( ) function, you must use gc_GetMetaEventEx( ) to retrieve the metaevent.

The gc_GetMetaEventEx( ) function has the same functionality and requirements as the gc_GetMetaEvent( ) function. For more information, see the gc_GetMetaEvent( ) function description.

Parameter	Description
metaeventp	points to the METAEVENT structure to be filled in by this function.See METAEVENT for more information.
evt_handle	SRL event handle used to identify a particular event

Termination Events

None

Cautions

• The gc_GetMetaEvent( ) or gc_GetMetaEventEx( ) function must be the first function called before processing any Global Call event.
• 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 programming models, use the gc_GetMetaEvent( ) function.
• An application should call the gc_GetMetaEventEx( ) 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.
• When calling the gc_GetMetaEventEx( ) function from multiple threads, ensure that your application uses unique thread-related METAEVENT data structures or ensure that the METAEVENT data structure is not written to simultaneously.

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 event retrieval wherein the SRL gets the event and then the extended gc_GetMetaEventEx( ) function fills in the METAEVENT data structure.

/*
 * Do SRL event processing
 */ 
hdlcnt = 0;
hdls[ hdlcnt++ ] = GetGlobalCallHandle();
hdls[ hdlcnt++ ] = GetVoiceHandle(); 
/* Wait selectively for devices that belong to this thread */ 
rc = sr_waitevtEx(   hdls, 
                     hdlcnt,
                     PollTimeout_ms,
                     &evtHdl 
                 );
    if (rc != SR_TMOUT) {
        /*
         *  Update 
         */
        rc = gc_GetMetaEventEx(&g_Metaevent, evtHdl);
        if (rc != GC_SUCCESS) {
            /* process error return */
            gc_ErrorInfo( &gc_error_info );
            printf ("Error: gc_GetMetaEventEx() 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);
        } 
    rc = vProcessCallEvents(  );
    } 

See Also

• gc_GetCRN( )
• gc_GetLineDev( )
• gc_GetMetaEvent( )
• gc_ResultInfo( )
• gc_ResultValue( ) (deprecated)

Click here to contact Telecom Support Resources