gc_AttachResource( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_AttachResource (linedev, resourceh, resourceattrp, retblkpp, resourcetype, mode)
Inputs:	LINEDEV linedev	Global Call line device handle
	int resourceh	voice or media device handle
	GC_PARM_BLKP resourceattrp	pointer to voice or media attribute information
	GC_PARM_BLKP* retblkpp	pointer to address of GC_PARM_BLK structure where voice or media attribute information is to be returned
	int resourcetype	type of resource
	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† IP (host-based stack and embedded stack†) †See the Global Call Technology User's Guides for additional information.

Description

The gc_AttachResource( ) function attaches a voice or media resource to a line device and provides optional capability exchange. By attaching the resource, an association is made between the line device and the voice or media resource channel. The resource channel specified by the device handle, resourceh, will be used to handle related Global Call functions requiring a voice or media resource for that line device.

Parameter	Description
linedev	Global Call line device handle
resourceh	SRL device handle for the voice or media resource that is to be attached to the line device
resourceattrp	points to the GC_PARM_BLK structure containing attributes of the voice or media resource being specified by resourceh. See the appropriate Global Call Technology User's Guide for information about how to specify resource attributes.
retblkpp	points to the address of GC_PARM_BLK structure where voice or media attribute information is to be returned
resourcetype	type of resource. Possible values are: GC_VOICEDEVICE GC_MEDIADEVICE
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

Termination Events

GCEV_ATTACH

indicates successful completion of the gc_AttachResource( ) function.

GCEV_ATTACH_FAIL

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

Cautions

• DM3 voice resources may only be attached to DM3 network resources; that is, they cannot be attached to Springware devices. Similarly, Springware resources cannot be attached to DM3 devices.
• A single media resource, a single voice resource, or both a voice and media resource may be attached to a Global Call line device at any given time.
• The call control libraries process and consume voice or media events of interest to the call control library before they reach the application.
• The gc_AttachResource( ) function does not perform time slot routing functions. The routing must be done during system configuration or performed by the application using the voice and network routing functions. Alternatively, the gc_OpenEx( ) function may be used to open, attach and route both the voice or media and the network resources.
• If this function is invoked for an unsupported technology, the function fails. The error value EGC_UNSUPPORTED is returned when the gc_ErrorInfo( ) function is used to retrieve the error code.
• If a protocol uses Global Tone Detection (GTD) tones for call analysis (assuming that GTD has not been disabled using the gc_SetParm( ) function), all pre-existing tone definitions for that voice resource are deleted. If the application requires additional tones after the initial set of tones are loaded, they must be redefined after calling the gc_AttachResource( ) function. The tone IDs cannot be in the range from 101-189.
• For protocols using GTD in any application that calls the gc_AttachResource( ) function several times on the same device (for example, when using resource sharing), the overhead associated with redundant tone deletion and definition may be avoided by calling the gc_SetParm(ldev, GCPR_LOADTONES, GCPV_DISABLE) function after the first call to the gc_AttachResource( ) function. Afterward, the application must reverse the effect of the gc_SetParm( ) function by issuing a gc_SetParm(ldev, GCPR_LOADTONES, GCPV_ENABLE) function when the call is complete.
• When using call progress analysis, the dx_initcallp( ) function must be called after calling the gc_AttachResource( ) function. The dx_initcallp( ) function initializes and activates PerfectCall call analysis on the channel and also adds all tones used in call analysis to the channel's GTD templates. Calling dx_initcallp( ) before calling gc_AttachResource( ) results in the deletion of all tones and the possible disabling of PerfectCall call analysis by the latter function.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function for error information. If the GCEV_ATTACH_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 <dxxxlib.h>
#include <gclib.h>
#include <gcerr.h> 
int attach(void)
{
    LINEDEV  ldev;                     /* GlobalCall line device handle */
    int      voiceh;                   /* Voice channel number */
    char     devname[50];
    GC_INFO  gc_error_info;            /* GlobalCall error information data */ 
    /*
     * Open line device for 1st network time slot on dtiB1 
     */ 
    if (gc_OpenEx(&ldev, devname, EV_SYNC, &ldev) == GC_SUCCESS) {
        voiceh = dx_open("dxxxB1C1", NULL);
        if (voiceh != -1) {
            if (gc_AttachResource(ldev, voiceh, NULL, NULL, GC_VOICEDEVICE,
                 EV_SYNC) == GC_SUCCESS) {
            /*
             * Proceed to route the voice and network resources together,
             * and then generate or wait for a call on the line device, 'ldev'.
             */
            }
            else {
                 /* process gc_AttachResource() error return as shown */
                 gc_ErrorInfo( &gc_error_info );
                 printf ("Error: gc_AttachResource() 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); 
            }
        } else {
            /* Process dx_open() error */
        }
    }
    else {
       /* process error from gc_OpenEx() using gc_ErrorInfo() */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_OpenEx() on devname: %s, GC ErrorValue: 0x%hx - %s, CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n",
          devname, 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_Close( )
• gc_Detach( )
• gc_GetNetworkH( ) (deprecated)
• gc_GetResourceH( )
• gc_GetVoiceH( ) (deprecated)
• gc_LoadDxParm( )
• gc_OpenEx( )

Click here to contact Telecom Support Resources