fx_getNSF( )

Description | Example | Errors

Name:	int fx_getNSF(dev,nsf_length,nsf_data)
Inputs:	int dev	fax channel device handle
	unsigned short nsf_length	number of bytes from NSF message to return
	char * nsf_data	pointer to buffer for NSF data
Returns:	0 if success
	-1 if failure
Includes:	srllib.h
	dxxxlib.h
	faxlib.h
Category:	miscellaneous
Mode:	synchronous

Description

The fx_getNSF( ) function returns the remote station's NSF message (T.30 Non-Standard Facilities), if available, for the specified channel containing the specified number of bytes.

Parameter	Description
dev	Specifies the channel device handle for the fax channel obtained when the channel was opened.
nsf_length	Total number of bytes in the NSF message to be stored in the buffer and number of bytes of the NSF message to retrieve.
nsf_data	A pointer to the buffer location where the NSF message specified in nsf_length is stored. The first word of nsf_data contains the actual length of the entire NSF message. The remaining bytes of nsf_data contain the bytes of the NSF message information.

To understand how the parameters are used, consider this example. If nsf_length is 10 bytes, then the nsf_data format is as follows:

• the first 2 bytes contain the number of bytes for the entire NSF message
• the remaining 8 bytes contain the first eight bytes of NSF message

NOTE:

If the actual NSF message requires fewer bytes than was specified in nsf_length, the number of bytes remaining is blank. If the actual NSF message contains more bytes than was specified in nsf_length, the NSF message is truncated.

The NSF message information is an optional, variable-length message that can contain fax hardware manufacturer-specific information. Manufacturers can use this information to support proprietary features for their products. The NSF message is sent by the remote station's fax machine and is available to the application after the completion of the first Phase B negotiation for a fx_sendfax( ), fx_rcvfax( ) or fx_rcvfax2( ) function call.

The NSF message information remains valid until the next Phase B negotiation is completed for the current function or until a new send or receive is initiated.

NOTE:

Phase B negotiations take place at the beginning of a fax send or receive function call and after a T.30 EOM (End of Message) message is sent by the transmitter.

To determine if the remote station sent an NSF message, call the ATFX_BSTAT( ) function. If the NSF message is available, this function returns a bitmap with the DFS_NSF bit set.

Example

#include <windows.h>  
#include <srllib.h>  
#include <dxxxlib.h>  
#include <faxlib.h>  
#define NSFMAX 128  
DF_IOTT iott[10];  
/* Handler for Phase B events. */  
int phb_hdlr( );  
main( )  
{  
   int voxdev;   /* Voice channel device handle. */  
   int dev;   /* Fax channel device handle. */  
   /*  
    * Open the channel using dx_open( ) to obtain the Dialogic  
    * VOICE device handle in voxdev.  
    * Open the channel using fx_open( ) to obtain the FAX channel  
    * device handle in dev.  
    */  
   .  
   .  
   /*  
    * Install handler using sr_enbhdlr( ) to service  
    * TFX_PHASEB events.  
    */  
    if (sr_enbhdlr(dev, TFX_PHASEB, phb_hdlr) == -1) {  
        printf("Failed to install Phase B handler \n");  
        return;  
    }  
   /*  
    * Call fx_sendfax( ) in asynchronous mode after setting  
    * up the DF_IOTT array.  Set DF_PHASEB bit in mode field  
    * to enable generation of Phase B events.  
    */  
   if (fx_sendfax(dev, iott, EV_ASYNC|DF_PHASEB) == -1) {  
      printf("Error - %s (error code %d)\n",  
         ATDV_ERRMSGP(dev),ATDV_LASTERR(dev));  
      if (ATDV_LASTERR(dev)==EDX_SYSTEM) {  
         /* Perform system error processing */  
      }  
   }  
   .  
   .  
}  
/*  
 * Handler registered with SRL to handle TFX_PHASEB events.  
 */  
int phb_hdlr( )  
{  
   char nsf_data[NSFMAX];  
   char * nsfp:  
   unsigned short nsflen;  
   int dev = sr_getevtdev( );  
   if (ATFX_BSTAT(dev) & DFS_NSF) {  
      /* Remote NSF available. */  
      if (fx_getNSF(dev, NSFMAX, nsf_data) == -1) {  
         /* Error processing */  
         .  
         .  
      } else {  
         /* Obtain number of bytes of NSF returned */  
         nsflen = * ((unsigned short *)&nsf_data[0]);  
         if (nsflen > NSFMAX) {  
            /*  
             * More NSF data available -- call fx_getNSF( )  
             * with larger data buffer if needed.  
             */  
             .  
             .  
         }  
         /* Set pointer to NSF data. */  
         nsfp = &nsf_data[2];  
         /* Display NSF (application specific handling). */  
         .  
         .  
      }  
   }  
   .  
   .  
   return(0);  
}

Errors

ATDV_LASTERR( ) returns the following fax error codes for the following reasons:

EFX_NODATA	The function is called before completion of the initial Phase B or the NSF message was not sent by the remote station.
EFX_NSFBUFF	nsf_length value is less than 2 (bytes).
EFX_UNSUPPORTED	The function is called for an unsupported board.

See Appendix D for a list of error codes that may be returned for this function.

Click here to contact Dialogic Customer Engineering