fx_originate( )

Description | Cautions | Example | Errors | See Also

Name:	int fx_originate(int dev, int mode)
Inputs:	int dev	fax channel device handle
	int mode	asynchronous/synchronous
Returns:	0 on success -1 on failure
Includes:	srllib.h dxxxlib.h faxlib.h
Category:	originate fax
Mode:	synchronous/asynchronous

Description

The fx_originate( ) function allows the DCS on hold feature to be used. The function results in a TFX_ORIGINATE or TFX_FAXERROR event, and the command can be stopped by fx_stopch( ).

Upon receipt of a TFX_ORIGINATE event, an fx_sendfax( ) should follow, and the application can call ATFX_BSTAT( ) and access FC_REMOTEID, fx_getDIS( ), fx_getNSF( ), ATFX_SPEED( ), ATFX_CODING( ), ATFX_ECM( ). All functions are filled with DF_DIS (Digital Identification Signal) values to avoid having to decode the DIS frame. Values are updated later, during the fx_sendfax( ), with DF_DCS (Digital Command Signal) values. When the fx_sendfax( ) is issued, the file/image format can be specified, including JPEG. See 7.6.2. Using the Fax API Library for Color Fax for additional information on sending JPEGs.

Parameter	Description
dev:	Specifies the device handle returned for the fax channel when the channel was opened.
mode:	The operation mode specifies whether the function should run asynchronously or synchronously.
	EV_ASYNC	Run asynchronously. Returns -1 to indicate failure to initiate. Returns 0 to indicate successful initiation and generates a TFX_ORIGINATE message once the DIS is detected, or TFX_FAXERROR if it is not detected.
	EV_SYNC	Run synchronously. Returns 0 on success and -1 on failure.

Cautions

• This function is supported on DM3 boards only.
• You must call the fx_initstat(DF_TX) function at least once prior to calling fx_originate( ).
• In Fax Resource Only Cluster (FROC) configurations (Fax24/Fax30 = Fax Cluster that has a timeslot), you must issue fx_listen( ) prior to calling fx_sendfax( ), fx_rcvfax( ) or fx_originate( ). Otherwise, these functions will return an error.
• If the fx_sendfax( ) is not received within the 20s (limited by the T1 timer + security margin), the fax session will be aborted and result in TFX_FAXERROR.

Example

#include <stdio.h>  
#include <errno.h>  
#include <windows.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <faxlib.h>  
#include <fcntl.h>  
#include <sys\types.h>  
#include <sys\stat.h>  
#include <io.h>  
#include <conio.h>  
int        dev; /* Fax channel device handle. */  
DF_IOTT   iott;  
int catchall( );  
int main(int argc, char* argv[])  
{  
    int CanRun = 1;  
    int mode = SR_STASYNC;  
    /* Set SRL to turn off creation of internal thread */  
    if( sr_setparm( SRL_DEVICE, SR_MODELTYPE, &mode ) == -1 ){  
        printf( "Error: cannot set srl mode\n" );  
        exit( 1 );  
    }  
    /*  
    * Open the channel using fx_open( ) to obtain the FAX  
    * channel device handle in dev.  
    */  
    if ((dev = fx_open("dxxxB1C1", NULL)) == -1) {  
        /* Error opening device. */  
        printf("Error opening channel, errno = %d\n", errno);  
        exit(1);  
    }  
    /*  
    * If this is not a Dm3 Fax channel (return type DFS_FAXDM3)  
    * warn the user.  
    */  
    if (ATFX_CHTYPE(dev) != DFS_FAXDM3) {  
        printf("Function fx_originate is not supported\n");  
    } else {  
        /* Open the file as read-only. */  
        iott.io_fhandle = dx_fileopen("sample.tif" ,O_RDONLY|O_BINARY,0);  
        /*  
        * Set up the DF_IOTT structure as the default and then  
        * change the necessary fields.  
        */  
        fx_setiott(&iott, iott.io_fhandle, DF_TIFF, DFC_AUTO);  
        iott.io_type |= IO_EOT;  
        printf("Press SPACE to show fx_originate usage, or ESC to exit\n");  
        while (CanRun) {  
            if (sr_waitevt(100) != -1) {  
                catchall( );  
            }  
            if (kbhit( )) {  
                switch(getch( )) {  
                case 27: /* Esc */  
                    CanRun = 0;  
                    break;  
                case ' ': /* Space */  
                    /* Set initial state of FAX channel to TRANSMITTER. */  
                    if (fx_initstat(dev, DF_TX) == -1) {  
                        printf("Error - %s (error code %d)\n", ATDV_ERRMSGP(dev),  
                            ATDV_LASTERR(dev));  
                        if (ATDV_LASTERR(dev) == EDX_SYSTEM) {  
                            printf("errno = %d\n", errno);  
                        }  
                    } else {  
                        if (iott.io_fhandle != -1) {  
                            printf("Issue our fx_originate\n");  
                            fx_originate(dev, EV_ASYNC);  
                        }  
                    }  
                    break;  
                }  
            }  
        }  
        dx_fileclose(iott.io_fhandle);  
    }  
    /*  
    * close the channel using fx_close( )  
    */  
    fx_close(dev);  
    return 0;  
}  
/* Event handler. */  
/*  
* This routine gets called when sr_waitevt( ) receives any event.  
* Maintain a state machine for every channel and issue the  
* appropriate function depending on the next action to be  
* performed on the channel.  
*/  
int catchall( )  
{  
    int dev;  
    dev = sr_getevtdev( );  
    /* Determine the event. */  
    switch(sr_getevttype( )) {  
    case TFX_ORIGINATE:  
        {  
            long BStat = ATFX_BSTAT(dev);  
            char DisBuf[100]={"N/A"};  
            char RemoteId[100]={"N/A"};  
            if (BStat & DFS_REMOTEID) {  
                if (fx_getparm(dev, FC_REMOTEID, RemoteId)!=0) {  
                }  
            }  
            if (BStat & DFS_DIS) {  
                DF_DIS DfDis;  
                if (fx_getDIS(dev, &DfDis)==-1) {  
                }  
                else {  
                    /* should translate DIS to a string */  
                    strcpy(DisBuf, "Present");  
                }  
            }  
            if (BStat & DFS_NSF) {  
            /*...    */  
            }  
            printf("Receiver is capable of: speed %ld, resln %ld,"  
                "width %ld, Ecm %ld\n", ATFX_SPEED(dev),  
                ATFX_RESLN(dev), ATFX_WIDTH(dev),  
                ATFX_ECM(dev));  
            printf("Information: Csid='%s' and Dis is %s\n",  
                RemoteId, DisBuf);  
            printf("Issue our fx_sendfax\n");  
            /*  
            * Depending the capabilities, Parameter can be adjusted  
            * and the user is capable of pointing to the appropriate  
            * iott structure (e.g., Raw Color Fax or simple tiff image)  
            */  
            fx_sendfax(dev, &iott,EV_ASYNC|DF_PHASEB|DF_PHASED);  
        }  
        break;  
    case TFX_FAXSEND:  
        /* The document has been successfully sent. */  
        printf("Sent %ld pages at speed %ld, resln %ld,"  
            "width %ld\n", ATFX_PGXFER(dev), ATFX_SPEED(dev),  
            ATFX_RESLN(dev), ATFX_WIDTH(dev));  
        /* Fax session completed. */  
        printf("Press ESC to exit\n");  
        break;  
    case TFX_PHASEB:  
        printf("Phase B event\n");  
        /* extract usual information from here */  
        break;  
    case TFX_PHASED:  
        printf("Phase D event\n");  
        /* extract usual information from here */  
        break;  
    case TFX_FAXERROR:  
        /* Error during the fax session. */  
/*        print_err(dev); */  
        printf("Phase E status %ld\n", ATFX_ESTAT(dev));  
        /* Application specific error handling. */  
            break;  
    default:  
            break;  
    } /* End of switch. */  
    return(0);  
}

Errors

TFX_ORIGINATE	Successful fax origination
TFX_FAXERROR	Error in processing
EFX_UNSUPPORTED	Unsupported function. This error returned if this function is attempted on a non-DM3 board

Refer to the error type tables found in the Fax Software Reference. Error defines can be found in faxlib.h.

See Also

• fx_getDIS( )
• fx_getNSF( )
• fx_stopch( )
• ATFX_SPEED( )
• ATFX_CODING( )
• ATFX_ECM( )

Click here to contact Dialogic Customer Engineering