Version

Appendix C

Data Structures

Introduction

Parameter Structures

: NFX_TRANSMIT_PARMS
: NFX_RECEIVE_PARMS
: NFX_DOC_PARMS
: NFX_CONVERT_PARMS

Status Structures

: NFX_FAX_STATUS
: NFX_DOC_STATUS
: NFX_CHECK_STATUS

Introduction

This chapter presents the data structures used in the NaturalFax Application Programming Interface. NaturalFax stores system parameters, document status, and fax session status in its data structures. Appendix D provides a detailed description of each parameter. All NaturalFax data structures are defined in nfxdef.h. Refer to the files list for the NaturalFax's installed directory structure for the exact path to the NaturalFax header files.

Parameter Structures

NaturalFax uses parameter data structures to specify the behavior of fax functions. CT Access parameter functions retrieve and change the values of a specified parameter structure. If a function is governed by parameters, then one of its arguments is a pointer to the relevant parameter structure. The developer can fill in and pass a parameter structure in the function call, or accept the default parameter values by passing a NULL pointer.
The parameter data structures are: NFX_TRANSMIT_PARMS NFX_RECEIVE_PARMS NFX_DOC_PARMS NFX_CONVERT_PARMS

NFX_TRANSMIT_PARMS

The NFX_TRANSMIT_PARMS structure is used to specify how the fax transmission will behave by controlling attributes such as baud rate, file encoding formats, and resolution. This structure is defined as follows: typedef struct { DWORD size; DWORD modemtype; /* NFX_MODEM_TYPE_V17, NFX_MODEM_TYPE_V27 */ /* or NFX_MODEM_TYPE_V29 */ DWORD minrate; /* NFX_BIT_RATE_2400, NFX_BIT_RATE_4800, */ /* NFX_BIT_RATE_7200, or NFX_BIT_RATE_9600 */ DWORD resolution; /* NFX_RESOLUTION_HIGH, NFX_RESOLUTION_LOW, or */ /* NFX_RESOLUTION_SUPER_HIGH */ DWORD encoding; /* NFX_ENCODE_1D, NFX_ENCODE_2D, or */ /* NFX_ENCODE_MMR */ DWORD pagewidth; /* NFX_PAGE_WIDTH_A4, NFX_PAGE_WIDTH__B4, or */ /* NFX_PAGE_WIDTH_A3 */ DWORD OTFmode; /* NFX_OTF_NEVER, NFX_OTF_ALWAYS, */ /* or NFX_OTF_ONLY_IF_FAIL */ DWORD useECM; /* NFX_YES or NFX_NO */ DWORD useCNG; /* NFX_YES or NFX_NO */ DWORD PRIenabled;/* NFX_YES or NFX_NO */ DWORD timeout; /* number of seconds to wait for receiver */ DWORD retrainaction; /* NFX_RTN_REPEAT_PAGE or NFX_RTN_NEXT_PAGE */ DWORD addheader; /* NFX_YES, NFX_NO or NFX_CUSTOM */ INT32 level; /* transmit level in tenths of dBm (-150 to -60) */ INT32 threshold; /* lowest level for receive, in tenths of dBm */ DWORD NSFlength; /* length of NSF field or 0 if none */ char SID[NFX_MAX_SID]; /* Subscriber ID string */ BYTE NSF[NFX_MAX_NSF]; /* default NSF for session */ char custom_header[NFX_MAX_HEADER]; /* customizable fax header */ } NFX_TRANSMIT_PARMS;

NFX_RECEIVE_PARMS

The NFX_RECEIVE_PARMS structure is used to specify how fax reception will behave by controlling attributes such as the baud rate, file encoding format, and the resolution that will be accepted by the receiving fax terminal. This structure is defined as follows: typedef struct { DWORD size; DWORD modemtype; /* NFX_MODEM_TYPE_V17, NFX_MODEM_TYPE_V27 */ /* or NFX_MODEM_TYPE_V29. */ /* Advertised capabilities for fax receiver */ DWORD minrate; /* NFX_BIT_RATE_2400, NFX_BIT_RATE_4800, */ /* NFX_BIT_RATE_7200, or NFX_BIT_RATE_9600 */ DWORD resolution; /* NFX_RESOLUTION_HIGH, NFX_RESOLUTION_LOW, */ /* NFX_RESOLUTION_SUPER_HIGH */ DWORD encoding; /* NFX_ENCODE_1D, NFX_ENCODE_2D, */ /* NFX_ENCODE_MMR, or NFX_ENCODE_TIFF_S */ DWORD pollingenabled; /* NFX_YES or NFX_NO */ DWORD badlineaction; /* NFX_BAD_LINE_ACTION_NONE, */ /* NFX_BAD_LINE_ACTION_DROP, */ /* NFX_BAD_LINE_ACTION_REPT, or */ /* NFX_BAD_LINE_ACTION_TICK */ DWORD pagewidth; /* NFX_PAGE_WIDTH_A4. NFX_PAGE_WIDTH__B4, or */ /* NFX_PAGE_WIDTH_A3 */ DWORD OTFmode; /* NFX_OTF_NEVER, NFX_OTF_ALWAYS, or */ /* NFX_OTF_ONLY_IF_FAIL */ DWORD useECM; /* NFX_YES or NFX_NO */ DWORD lineerrors; /* % line errors before retrain negative */ INT32 level; /* transmit level in tenths of dBm */ /* (-150 to -60) */ INT32 threshold; /* lowest level for receive, in tenths of dBm */ DWORD NSFlength; /* Length of NSF field or 0 if none */ char SID[NFX_MAX_SID]; /* Subscriber ID string */ BYTE NSF[NFX_MAX_NSF]; /* default NSF for session */ } NFX_RECEIVE_PARMS;
Specifying NFX_ENCODE_TIFF_S causes the output file to be written to the TIFF-S specification. Values will be overridden to 1D for encoding, low for resolution, and A4 for page width.

NFX_DOC_PARMS

The NFX_DOC_PARMS structure is used to specify details about each document to be enqueued, such as encoding format and page width. The doc_resolution, doc_encoding, and doc_page_width fields apply only to documents in a receive queue. NFX_DOC_PARMS is defined as follows: typedef struct { DWORD size; /* size of this structure */ DWORD resolution; /* NFX_RESOLUTION_HIGH, NFX_RESOLUTION_LOW */ /* or NFX_RESOLUTION_SUPER_HIGH */ DWORD encoding; /* NFX_ENCODE_1D, NFX_ENCODE_2D or */ /* NFX_ENCODE_MMR */ DWORD pagewidth; /* NFX_PAGE_WIDTH_A4, NFX_PAGE_WIDTH_B4 or */ /* NFX_PAGE_WIDTH_A3 */ } NFX_DOC_PARMS;

NFX_CONVERT_PARMS

The NFX_CONVERT_PARMS structure is used to specify the input and output file format details for use by the nfxConvertFileDirect function. This structure is defined as follows: typedef struct { DWORD size; DWORD type; /* NFX_TIFF_F or NFX_TIFF_S */ DWORD resolution; /* NFX_RESOLUTION_HIGH, NFX_RESOLUTION_LOW, */ /* or NFX_RESOLUTION_SUPER_HIGH */ DWORD encoding; /* NFX_ENCODE_1D, NFX_ENCODE_2D, */ /* NFX_ENCODE_MMR, or NFX_ENCODE_TIFF_S */ DWORD pagewidth; /* NFX_PAGE_WIDTH_A4, NFX_PAGE_WIDTH_B4 */ /* or NFX_PAGE_WIDTH_A3 */ DWORD badlineaction; /* NFX_BAD_LINE_ACTION_NONE, */ /* NFX_BAD_LINE_ACTION_DROP, */ /* NFX_BAD_LINE_ACTION_REPT, or */ /* NFX_BAD_LINE_ACTION_TICK */ } NFX_CONVERT_PARMS;
Specifying NFX_ENCODE_TIFF_S for encoding or NFX_TIFF_S for type causes the output file to be written to the TIFF-S specification. Values will be overridden to 1D for encoding, low for resolution, and A4 for page width.

Status Structures

NaturalFax records the status of fax sessions, and the status of each document processed during a fax session. The status data structures are: NFX_FAX_STATUS NFX_DOC_STATUS NFX_CHECK_STATUS

NFX_FAX_STATUS

The NFX_FAX_STATUS structure stores the status of the currently active fax session. It is current with respect to the most recent NaturalFax event. This structure is defined as follows: typedef struct { DWORD size; DWORD rate; DWORD ecm; /* error correction mode NFX_YES or NFX_NO */ DWORD resolution; DWORD encoding; DWORD pagewidth; DWORD mode; /* NFX_MODE_IDLE, NFX_MODE_NEGOTIATING, */ /* NFX_MODE_TRANSMITING, NFX_MODE_RECEIVING, */ /* NFX_MODE_DISCONNECTING or NFX_MODE_FINISHED */ DWORD error; /* Last error code generated */ DWORD docnumber; /* Current document in progress */ DWORD pagenumber; /* Current page of the document */ DWORD badlines; /* Number of bad lines (or bad frames in */ /* ECM mode) during current session */ char filename[NFX_FILENAME_MAX]; /* Name of current file processed */ char remoteSID[NFX_MAX_SID]; /* Received SID from remote station */ BYTE remoteNSF[NFX_MAX_NSF]; /* Received NSF from remote station */ DWORD snr; /* signal to noise ratio in dB */ DWORD rx_training_zeros; /* training zeros in the TCF */ /* in tens of milliseconds */ } NFX_FAX_STATUS;

NFX_DOC_STATUS

The NFX_DOC_STATUS structure stores the status of one document entry in a particular document queue. This structure is defined as follows: typedef struct { DWORD size; DWORD docnum; /* Entry number in queue */ DWORD processedstatus; /* Has this document been sent? */ DWORD lasterror; /* Last error code (if any) for doc */ DWORD pagecount; /* Number of pages (for receive) */ DWORD startpage; /* Page to start at (for retransmit) */ DWORD lastpagesent; /* Last page # successfully sent */ DWORD retranscount; /* Number of retries */ DWORD docencoding; /* 1D (MH) or 2D (MR) or MMR */ DWORD docresolution; /* Resolution: low, high, superhigh */ DWORD docwidth; /* Width: A4, A3, B4 */ DWORD negotiatedencoding; /* Encoding used for transfer */ DWORD negotiatedrate; /* Baud rate used for transfer */ DWORD negotiatedresolution; /* Resolution used for transfer */ DWORD negotiatedwidth; /* Page width used for transfer */ DWORD badlinecount; /* Number of bad lines in doc received. */ /* Or, in ECM mode bad frames txed/rxed */ DWORD doctime; /* time document processing started */ DWORD duration; /* seconds elapsed processing doc */ char filename[NFX_FILENAME_MAX]; /* filename arg from nfxEnqueueDoc */ } NFX_DOC_STATUS;

NFX_CHECK_STATUS

The NFX_CHECK_STATUS structure stores the status of the image format found on each page of a TIFF file when nfxCheckTIFF is executed. This structure is defined as follows: typedef struct { DWORD size; /* size of this structure */ DWORD resolution; /* NFX_RESOLUTION_HIGH, NFX_RESOLUTION_LOW, */ /* or NFX_RESOLUTION_SUPER_HIGH */ DWORD encoding; /* NFX_ENCODE_1D, NFX_ENCODE_2D, or */ /* NFX_ENCODE_MMR */ DWORD pagewidth; /* NFX_PAGE_WIDTH_A4 or NFX_PAGE_WIDTH_B4 or */ /* NFX_PAGE_WIDTH_A3 */ DWORD lines; /* number of lines on the page */ DWORD badlines; /* number of bad lines on the page */ } NFX_CHECK_STATUS;

Version

Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com