GDK Version 5.0 Programming Reference Manual gfdRemoteRequest( )

gfdRemoteRequest( )

Obsolete APIs

Name:

int gfdRemoteRequest (int chassis, int channel, int command, int func, int parm, char buffer, int buffer_length, int *res)

Inputs:

int chassis

   · Chassis number (always zero).

int channel

   · Logical channel number (use 0 for the Dispatcher, GFDCP).

int command

   · A command from Table 36.

int func

   · First parameter.

int parm

   · Second parameter.

char *buffer

   · Command buffer.

int buffer_length

   · Length of command buffer.

Outputs:

int *res

   · Result of the command when it is processed.

Returns:

0 or GFD_SUCCESS

   · Successful. Check the result code passed back (res) for result of the actual command.

GFDCHANNEL_FAILED

   · State of the target channel is "failed."

GFDINVALID_CHANNEL

   · Specified channel is not in the range for which the Dispatcher is configured.

GFDREMOTE_SPARM_ERROR

   · Buffer length specified in gfdRemoteRequest is greater than internal buffer size (currently, 1024).

GFD_ACCESS_DENIED

   · Failed to properly open or close the remote (fax) handle of the named pipe.

Includes:

gfdmsg.h
gfdipc.h
gfqctl.h
gfq.h

Description

The gfdRemoteRequest( ) function allows the calling application to send a message to the fax channel to perform the requested function or operation. "Remote Request" refers to the fact that the host application is requesting the "remote" software to execute certain commands or change certain parameters.

The gfdRemoteRequestcall contains the chassis and channel number for the communication subsystem component to execute the remote function. The channel number is the logical channel number within a chassis. Channel number 0 is used to refer to the GDK Dispatcher for that chassis. Channel number 1 is the first logical fax channel, channel number 2 is the second logical fax channel, and so forth.

There are several types of functions that the gfdRemoteRequest can issue. You can use gfdRemoteRequest to issue configuration commands from the gfax.$dc file. Some configuration commands have only one argument after the channel number. GFXSHUTDOWN is one such command. A typical GFXSHUTDOWN setting in the gfax.$dc file is:

	GFXSHUTDOWN <channel> 3

To change the shutdown state of a fax channel using the gfdRemoteRequest, the following can be used:

	status = gfdRemoteRequest (0, channel,GFXSHUTDOWN, 0, 3, "", 0, &result);

Other configuration commands have two arguments. GFXECM has one argument to enable ECM (error correction mode) for send mode and another argument to enable ECM for receive mode. A typical argument to enable ECM for send only is:

GFXECM <channel> 1 0

The equivalent gfdRemoteRequest call is:

	status = gfdRemoteRequest(0, channel, GFXECMMODE, 1, 0, "", 0, &result);

For the configuration commands that require one argument, that argument is passed as the fifth argument to gfdRemoteRequest, using the function parameter. For configuration commands that require two arguments, they are passed in order as the fourth and fifth parameters to gfdRemoteRequest.

In the section discussing the creation of user-defined pipes and enabling event notification and response, we saw that the gfdRemoteRequest function is used to send messages to the fax channel. The following examples show how to use gfdRemoteRequest to send the most common messages relating to pipe creation, event notification, and event response.

Example

int status;

int result;  
/* To open the remote (fax) end of a pipe already created using gfdMakeNmPipe( ):*/

status = gfdRemoteRequest(0, channel, XXX_gfdOpen, 0, 0, pipeName, strlen(pipename) + 1, faxHhandle):  
/* To close the remote (fax) end of a pipe:*/  
status = gfdRemoteRequest(0, channel, XXX_gfdClose, 0, faxHandle, NULL, 0, &result);  
/* To enable event notification only for the INFOEXCHANGE event:*/  
status = gfdRemoteRequest(0, channel, GFXRTNHANDLE, GFXRTBP_INFOEXCHANGE, faxHandle, NULL, 0, &results);  
/* To enable event response on a different handle for the INFOEXCHANGE event:*/  
status = gfdRemoteRequest(0, channel, GFXRTRHANDLE, GFXRTBP_INFOEXCHANGE, responseHandle, NULL, 0, &result);  
/*To disable the default action for the CALLTERM event:*/  
status = gfdRemoteRequest(0, channel, GFXRTACTION, GFXRTBP_CALLTERM, GFXRT_ABORT, NULL, 0, &result);  
/*To change the timeout for the INFOEXCHANGE event to 5 seconds:*/  
status = gfdRemoteRequest(0, channel, GFXRTTIMEOUT, GFXRTBP_INFOEXCHANGE, 5, NULL, 0, &result);

Additional Information

The gfdRemoteRequest also provides one more capability. When using the interactive fax programming model, the gfdRemoteRequest is used to submit queue records to the fax channel to give the fax channel its operation. To send a fax, for example, a queue record must be created and filled out, and then submitted to the fax channel via gfdRemoteRequest as in the code fragment below:

GFQRECORD qrec;  
qrec.operation = GFQDIAL_SEND;  
strcpy(qrec.fn_send, "test001.tif");  
strcpy(qrec.phone_no, "1-408-744-1900");  
status = gfdRemoteRequest(0, channel, GFXQRECORD, 0, 0, 

 (char *)&qrec, sizeof(GFQRECORD), &result);

To send a message to the fax channel telling it to wait for an incoming call, and then receive a fax, a similar gfdRemoteRequest is used:

GFQRECORD qrec;  
qrec.operation = GFQANSWER_RECEIVE;  
strcpy(qrec.fn_received, "a001p001.tif");  
status = gfdRemoteRequest(0, channel, GFXQRECORD, 0, 0, 

 (char *)&qrec, sizeof(GFQRECORD), &result);

The gfdRemoteRequest is always used to send queue records in the same way as above. Typically, the only difference is the operation field of the queue record.

NOTE:: More message options are specified in GFQCTL.H.

Table 36. gfdRemoteRequest Commands

Command

Configuration Commands¹

Channel

Func

Parm

Buffer

Fax-Agent Control Messages

GFXECMMODE

GFXECM

channel

rx

tx

null string

GFXFAXCONTROL

GFXFAXC

channel

arg

cmd

null string

GFXFINE

GFXFINE

channel

0

parm

null string

GFXFORMAT

GFXFORM

channel

0

parm

null string

GFXGFCONTROL

GFCCONTROL

channel

arg

cmd

null string

GFXMDMCONTROL

MODEMCTRL

channel

arg

cmd

null string

GFXSCANTIME

GFXSCANTIME

channel

0

parm

null string

GFXSHUTDOWN

GFXSHUTDOWN

channel

0

parm

null string

GFXSPEAKER

GFXSPEAKER

channel

0

parm

null string

GFXWAIT

GFXWAIT

channel

0

parm

null string

GFXCARRY_ON

GFXCARRYON

channel

0

parm

null string

GFXREJ_BURST

GFXREJBURST

channel

0

parm

null string

GFXREJ_COUNT

GFXREJCOUNT

channel

0

parm

null string

GFXREJ_PERCENT

GFXREJPERCENT

channel

0

parm

null string

GFXRTN_RETRAIN

GFXRTNRETRAIN

channel

0

parm

null string

GFXRTP_RETRAIN

GFXRTPRETRAIN

channel

0

parm

null string

Set Receive Directory

GFXRECVPATH

GFXRECVPATH

channel

0

0

"path"

Output-Conversion-Agent Control Messages

GFXBOTTOMMARGIN

GFXBOTTOMMARGIN

channel

0

parm

null string

GFXCHARSET

GFXCHARSET

channel

0

parm

null string

GFXEXTEND

GFXEXTEND

channel

0

parm

null string

GFXLEFTMARGIN

GFXLEFTMARGIN

channel

0

parm

null string

GFXPAGELENGTH

GFXPAGELENGTH

channel

0

parm

null string

GFXRIGHTMARGIN

GFXRIGHTMARGIN

channel

0

parm

null string

GFXSPACING

GFXSPACING

channel

0

parm

null string

GFXTABSTOP

GFXTABSTOP

channel

0

parm

null string

GFXTOPMARGIN

GFXTOPMARGIN

channel

0

parm

null string

Queue Record

GFXQRECORD

-

channel

0

parm

qrec

Event Notifications

GFRTACTION

-

channel

event id²

action²

null string

GFXENABLE

-

channel

event id²

notify/
response handle

null string

GFXRTNHANDLE

-

channel

event id²

notify handle

null string

GFXRTRHANDLE

-

channel

event id²

response handle

null string

GFXRTTIMEOUT

-

channel

event id²

seconds

null string

Named Pipe

XXX_gfdClose³

-

0

0

0

pipe name

XXX_gfdOpen³

-

0

0

0

pipe name

¹ See the GDK, Installation and Configuration Guide for Windows for details on the configuration commands.

² See Table 37 for values.

³ These commands are defined in xxxmsgs.h.

Table 37. Event Identifiers and Default Actions

Category

Symbolic Name

Event ID

Call Answer

GFXRTBP_ANSWER

Call Pending

GFXRTBP_CALLPENDING

Call Termination

GFXRTBP_CALLTERM

DCS Received

GFXRTBP_DCS_RECV

Dial

GFXRTBP_DIAL

DIS Received

GFXRTBP_DIS_RECV

Information Exchange

GFXRTBP_INFOEXCHANGE

Page Break

GFXRTBP_PAGE_BREAK

Action

Abort

GFXRT_QUEUE

Continue

GFXRT_CONTINUE

Queue

GFXRT_QUEUE

Obsolete APIs

The following functions have been removed from the 3.x releases of the GDK software.

gfdBoardDetect( ) has been replaced by glHWDetect( ).
gfdGenerateConfig( ) has been replaced by Control Panel configuration utility.
gfqReadOne( ) has been replaced by gfqFindNext( ).
gfqReport( ) has been replaced by gfqFindFirst( ).
gfdStartDispatcherSVC( ) is redundant to the Win32 StartService( ) API.

Click here to contact Dialogic Customer Engineering

Name:	int gfdRemoteRequest (int chassis, int channel, int command, int func, int parm, char buffer, int buffer_length, int *res)
Inputs:	int chassis	· Chassis number (always zero).
	int channel	· Logical channel number (use 0 for the Dispatcher, GFDCP).
	int command	· A command from Table 36.
	int func	· First parameter.
	int parm	· Second parameter.
	char *buffer	· Command buffer.
	int buffer_length	· Length of command buffer.
Outputs:	int *res	· Result of the command when it is processed.
Returns:	0 or GFD_SUCCESS	· Successful. Check the result code passed back (res) for result of the actual command.
	GFDCHANNEL_FAILED	· State of the target channel is "failed."
	GFDINVALID_CHANNEL	· Specified channel is not in the range for which the Dispatcher is configured.
	GFDREMOTE_SPARM_ERROR	· Buffer length specified in gfdRemoteRequest is greater than internal buffer size (currently, 1024).
	GFD_ACCESS_DENIED	· Failed to properly open or close the remote (fax) handle of the named pipe.
Includes:	gfdmsg.h gfdipc.h gfqctl.h gfq.h

Command	Configuration Commands¹	Channel	Func	Parm	Buffer
Fax-Agent Control Messages
GFXECMMODE	GFXECM	channel	rx	tx	null string
GFXFAXCONTROL	GFXFAXC	channel	arg	cmd	null string
GFXFINE	GFXFINE	channel	0	parm	null string
GFXFORMAT	GFXFORM	channel	0	parm	null string
GFXGFCONTROL	GFCCONTROL	channel	arg	cmd	null string
GFXMDMCONTROL	MODEMCTRL	channel	arg	cmd	null string
GFXSCANTIME	GFXSCANTIME	channel	0	parm	null string
GFXSHUTDOWN	GFXSHUTDOWN	channel	0	parm	null string
GFXSPEAKER	GFXSPEAKER	channel	0	parm	null string
GFXWAIT	GFXWAIT	channel	0	parm	null string
GFXCARRY_ON	GFXCARRYON	channel	0	parm	null string
GFXREJ_BURST	GFXREJBURST	channel	0	parm	null string
GFXREJ_COUNT	GFXREJCOUNT	channel	0	parm	null string
GFXREJ_PERCENT	GFXREJPERCENT	channel	0	parm	null string
GFXRTN_RETRAIN	GFXRTNRETRAIN	channel	0	parm	null string
GFXRTP_RETRAIN	GFXRTPRETRAIN	channel	0	parm	null string
Set Receive Directory
GFXRECVPATH	GFXRECVPATH	channel	0	0	"path"
Output-Conversion-Agent Control Messages
GFXBOTTOMMARGIN	GFXBOTTOMMARGIN	channel	0	parm	null string
GFXCHARSET	GFXCHARSET	channel	0	parm	null string
GFXEXTEND	GFXEXTEND	channel	0	parm	null string
GFXLEFTMARGIN	GFXLEFTMARGIN	channel	0	parm	null string
GFXPAGELENGTH	GFXPAGELENGTH	channel	0	parm	null string
GFXRIGHTMARGIN	GFXRIGHTMARGIN	channel	0	parm	null string
GFXSPACING	GFXSPACING	channel	0	parm	null string
GFXTABSTOP	GFXTABSTOP	channel	0	parm	null string
GFXTOPMARGIN	GFXTOPMARGIN	channel	0	parm	null string
Queue Record
GFXQRECORD	-	channel	0	parm	qrec
Event Notifications
GFRTACTION	-	channel	event id²	action²	null string
GFXENABLE	-	channel	event id²	notify/ response handle	null string
GFXRTNHANDLE	-	channel	event id²	notify handle	null string
GFXRTRHANDLE	-	channel	event id²	response handle	null string
GFXRTTIMEOUT	-	channel	event id²	seconds	null string
Named Pipe
XXX_gfdClose³	-	0	0	0	pipe name
XXX_gfdOpen³	-	0	0	0	pipe name

Category	Symbolic Name
Event ID
Call Answer	GFXRTBP_ANSWER
Call Pending	GFXRTBP_CALLPENDING
Call Termination	GFXRTBP_CALLTERM
DCS Received	GFXRTBP_DCS_RECV
Dial	GFXRTBP_DIAL
DIS Received	GFXRTBP_DIS_RECV
Information Exchange	GFXRTBP_INFOEXCHANGE
Page Break	GFXRTBP_PAGE_BREAK
Action
Abort	GFXRT_QUEUE
Continue	GFXRT_CONTINUE
Queue	GFXRT_QUEUE