gc_SetChanState( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int gc_SetChanState(linedev, chanstate, mode)
Inputs:	LINEDEV linedev	Global Call line device handle
	int chanstate	channel service state
	unsigned long mode	async or sync
Returns:	0 if successful <0 if failure
Includes:	gclib.h gcerr.h
Category:	optional call handling
Mode:	asynchronous or synchronous
Platform and Technology:	Springware: T-1/E-1†, ISDN PRI (T-1 only)† DM3: T-1/E-1†, ISDN†, Analog SS7† †See the Global Call Technology User's Guides for additional information.

Description

The gc_SetChanState( ) function sets the channel state of the indicated channel. When power is initially applied, all channels are placed in the In Service state.

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

Parameter	Description
linedev	Global Call line device handle
chanstate	service state of line. Possible values are: GCLS_INSERVICE inform driver that host is ready to receive and send a message GCLS_MAINTENANCE inform host that normal outbound traffic is not allowed and that only inbound test calls can be made GCLS_OUT_OF_SERVICE inform driver that host is not ready to receive or send messages. See the appropriate Global Call Technology User's Guide for inbound and outbound requests that will be rejected.
mode	set to EV_ASYNC for asynchronous execution or to EV_SYNC for synchronous execution

Termination Events

GCEV_SETCHANSTATE

indicates that the function was successful, that is, the request for a change in channel state was accepted.

GCEV_TASKFAIL

indicates that the function failed. For more information, see the "Error Handling" section in the Global Call API Programming Guide.

Cautions

• This function should only be invoked while in the Null call state. The Null call state occurs when a call to the gc_OpenEx( ), gc_ReleaseCallEx( ) or gc_ResetLineDev( ) function is terminated.
• Do not call gc_WaitCall( ) or gc_MakeCall( ) until this function completes.
• It is the responsibility of the application to recognize that the gc_SetChanState( ) function was used to put a channel in the maintenance (GCLS_MAINTENANCE) or the out-of-service (GCLS_OUT_OF_SERVICE) state. A GCEV_BLOCKED event is not necessarily generated. Do not call gc_WaitCall( ) or gc_MakeCall( ) while a channel is in the maintenance of out-of-service state.

Errors

If this function returns <0 to indicate failure, use the gc_ErrorInfo( ) function for error information. If the GCEV_TASKFAIL 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 following was done:
 *  IF not in the Null state, THEN
 *    issue gc_DropCall() function (if needed) and then the
 *    gc_ReleaseCallEx() function.
 */ 
int set_channel_InService(LINEDEV ldev)
{
    int            state;            /* State to which channel has to be set */
    GC_INFO  gc_error_info;   /* GlobalCall error information data */ 
    /*
     * Set channel to "INSERVICE" state 
     */
    state = GCLS_INSERVICE;          /* constant describing channel state */
    if (gc_SetChanState(ldev, state, EV_SYNC) != GC_SUCCESS) {
        /* process error return as shown */
        gc_ErrorInfo( &gc_error_info );
        printf ("Error: gc_SetChanState() 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 can change state again when necessary.
     */
    return (0);
} 

See Also

• gc_WaitCall( )

Click here to contact Telecom Support Resources