gc_Detach( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_Detach(linedev, voiceh, mode)
Inputs:	LINEDEV linedev	Global Call line device handle
	int voiceh	media device handle
	unsigned long mode	async or sync
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	voice and media
Mode:	asynchronous or synchronous
Platform and Technology:	Springware: T-1/E-1† DM3: T-1/E-1†, ISDN, Analog SS7 IP (host-based stack and embedded stack†) †See the Global Call Technology User's Guides for additional information.

Description

The gc_Detach( ) function is used to detach a voice or media resource from the line device. This breaks any association between the line device and the resource, which would have been attached previously to the line device using the gc_AttachResource( ) function.

When a gc_Close( ) function closes a line device, any attached voice or media resource is closed automatically. To keep the voice or media device open, first issue a gc_Detach( ) function and then issue the gc_Close( ) function. This will disassociate the voice or media device from the line device.

See also the appropriate Global Call Technology User's Guide for technology-specific information.

Parameter	Description
linedev	Global Call line device handle
voiceh	SRL device handle of the voice or media resource to be detached from the call control line device
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

Termination Events

GCEV_DETACH

indicates successful completion of the gc_Detach( ) function.

GCEV_DETACH_FAIL

indicates that the gc_Detach( ) function failed. For more information, see the appropriate Global Call Technology User's Guide.

Cautions

• The gc_Detach( ) function does not perform any routing or unrouting functions. For technologies where time slot routing is applicable, routing must be performed using the voice and network routing functions.
• If this function is invoked for an unsupported technology, the function fails. The error value EGC_UNSUPPORTED will be returned when the gc_ErrorInfo( ) function is used to retrieve the error code.
• If the gc_Detach( ) function is called during call setup, the application may receive an unexpected event. In addition, an unexpected event may be received if a call to the gc_Detach( ) function is followed by a call to gc_Close( ). These unexpected events can be ignored.
• In applicable technologies, gc_Detach( ) does not unload tones.
• Global Call functionality requiring a voice resource, such as gc_MakeCall( ) or gc_WaitCall( ) on R2 technologies, will fail if there are no voice resources attached.

Errors

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

#include <stdio.h>
#include <srllib.h>
#include <gclib.h>
#include <gcerr.h> 
/*
 * Assume the following has been done:
 *    1. The line device (ldev) has been opened, specifying a
 *       network time slot and a protocol. For example, 'devicename
 *       could be ":N_dtiB1T1:P_br_r2_i:V_dxxxB1C1" [E-1 CAS]
 *    2. The voice and network resources have been routed together
 *    3. Voice resource is no longer needed for this line device
 */ 
/* detaches the ldev's voice handle from ldev */
int detach(LINEDEV ldev)
{
    GC_INFO        gc_error_info;    /* GlobalCall error information data */
    int            voiceh;           /* Voice handle attached to ldev */ 
    if (gc_GetVoiceH(ldev, &voiceh) == GC_SUCCESS) {
        if (gc_Detach(ldev, voiceh, EV_SYNC) != GC_SUCCESS) {
           /* process error return as shown */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_Detach() on device handle: 0x%lx, GC ErrorValue: 0x%hx - %s, 
               CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
               ldev, 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);
        } 
        /*
         * Application should now unroute the voice and network resources from 
         * each other (using functions like nr_scunroute() or sb_unroute() to
         * complete the disassociation of them from each other.
         */
    } else {
        /* Process gc_GetVoiceH() error */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_GetVoiceH() on device handle: 0x%lx, GC ErrorValue: 0x%hx - %s,
               CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
               ldev, 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);
    }
    return (0);
} 

See Also

• gc_AttachResource( )
• gc_Close( )
• gc_OpenEx( )

Click here to contact Telecom Support Resources