(Page 1 of 1 in this chapter)


Appendix E

NaturalFax Parameters


Introduction

NaturalFax stores its parameters in data structures. The following sections describe each parameter in NFX_TRANSMIT_PARMS, NFX_RECEIVE_PARMS, NFX_DOC_PARMS, and NFX_CONVERT_PARMS. Each section lists the functions that are affected by the specified parameter structure, shows the data structure, and provides detailed information about each parameter in the structure. The parameters are listed in alphabetical order.

The following CT Access functions obtain or modify parameter information:

For more information about parameter management in CT Access, see the CT Access Developer's Reference Manual.

NFX_TRANSMIT_PARMS

The parameters in NFX_TRANSMIT_PARMS control the behavior of a fax transmission, including characteristics such as file encoding formats and resolution.

Dependent Functions

Related Data Structure

typedef struct 
{
  DWORD size;
  DWORD modemtype;   /* NFX_MODEM_TYPE_V17. NFX_MODEM_TYPE_V33,             */
      /* 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 or NFX_NO            */
  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_TRANSMIT_PARMS;

NFX_TRANSMIT_PARMS Structure Fields

The NFX_TRANSMIT_PARMS structure contains the following fields:

addheader
Type

DWORD

Units

None.

Default Value

NFX_YES

Allowed Values

NFX_YES, NFX_NO

Description

This field is mandatory for applications running in countries under FCC or DoC jurisdiction. This parameter indicates whether headers will be added to the transmitted image data. The header is a fixed string in the following format:

FROM: transmit_SID Date Time Page N of M

encoding
Type

DWORD

Units

None.

Default Value

NFX_ENCODE_1D

Allowed Values

NFX_ENCODE_1D, NFX_ENCODE_2D, or NFX_ENCODE_MMR

Description

Limits the image encoding format of fax images to be transmitted to 1D encoding. 1D encoding is supported by all Group 3 fax terminals. The actual encoding used depends on the value for this parameter, the encoding supported by the receiving fax terminal, and the encoding in the file to be transmitted. useECM must be set to NFX_YES to use NFX_ENCODE_MMR.

level
Type

INT32

Units

tenths of dBm

Default Value

-135

Allowed Values

-150 to - 60

Description

Specifies the transmission level. -150 corresponds to -15 dBm, -60 corresponds to -6 dBm.

minrate
Type

DWORD

Units

bps

Default Value

NFX_BIT_RATE_2400

Allowed Values

NFX_BIT_RATE_14400, NFX_BIT_RATE_12000, NFX_BIT_RATE_9600, NFX_BIT_RATE_7200, NFX_BIT_RATE_4800, NFX_BIT_RATE_2400

Description

Specifies the minimum allowed rate that NaturalFax will select for fax transmissions. This parameter can be used to limit the range of rates used. NFX_BIT_RATE_2400 and NFX_BIT_RATE_4800 specify the V.27ter modems at 2400 and 4800 bps, respectively. NFX_BIT_RATE_7200 and NFX_BIT_RATE_9600 specify the V.29 modems at 7200 and 9600 bps.

The transmit rate cannot drop below the minrate. Therefore, if the receiving fax terminal advertises only modems whose rates are below the minrate, then the fax session fails immediately with an NFXEVN_SESSION_DONE event with NFXERR_RATE_TOO_LOW in the reason field.

modemtype
Type

DWORD

Units

None.

Default Value

NFX_MODEM_TYPE_V17

Allowed Values

NFX_MODEM_TYPE_V27, NFX_MODEM_TYPE_V29, NFX_MODEM_TYPE_V17

Description

Specifies the preferred modem that can be selected for fax transmissions. Specifying a preferred modem sets an upper limit on the set of modems NaturalFax will consider when trying to match the receiving fax terminal's capabilities.

The following modems support the following rates of data transmission:

· V.27ter supports 2400 and 4800 bits per second (bps)

· V.17 supports 7200, 9600, 12,000, and 14,400 bps

· V.29 supports 7200 and 9600 bps

If NaturalFax drops to a modem type that supports lower transmission rates, it will attempt to use the highest rate for that modem type. If the transmitting fax terminal receives a "retrain negative" from the receiving fax terminal, and it is already using the rate specified by minrate, NaturalFax continues to use the rate specified by minrate.

If the transmitting fax terminal receives a "retrain negative" from the receiving fax terminal, NaturalFax attempts to use a lower transmission rate for the current modem. If the original rate is the lowest rate for the current modem, NaturalFax will attempt to use the modem that supports the next lowest transmission rate that is still at or above the minrate value.

NSF
Type

BYTE

Units

None.

Default Value

NULL

Allowed Values

A byte array between 0 and 54 bytes in length.

Description

Assigns the value to be used in the non-standard facilities frame on transmit.

NSFlength
Type

DWORD

Units

bytes

Default Value

0

Allowed Values

0 - 54

Description

Specifies the length of the NSF field given in TRANSMIT_PARMS.NSF. If this parameter is non-zero, the value in NSF will be used when negotiating with the remote fax terminal.

OTFmode
Type

DWORD

Units

None.

Default Value

NFX_OTF_NEVER

Allowed Values

NFX_OTF_NEVER, NFX_OTF_ALWAYS, NFX_OTF_ONLY_IF_FAIL

Description

Specifies when to perform on-the-fly conversion during a fax transmit operation. On-the-fly (OTF) conversion modifies the stored fax document's format (its encoding, resolution, and/or page size) before transmitting it. If OTF is enabled, actual format transmitted depends on the value for this parameter, the format supported by the receiving fax terminal, and the format in the original file to be transmitted. Set this parameter to NFX_OTF_NEVER to disable on-the-fly conversion. Set this parameter to NFX_OTF_ONLY_IF_FAIL to perform format conversions only when fax negotiations would otherwise fail. Set to NFX_OTF_ALWAYS to always perform a conversion.

pagewidth
Type

DWORD

Units

None.

Default Value

NFX_PAGE_WIDTH_A4

Allowed Values

NFX_PAGE_WIDTH_A4, NFX_PAGE_WIDTH_B4, NFX_PAGE_WIDTH_A3

Description

Specifies the page width of fax images to be transmitted. The actual page width used depends on the value for this parameter, the page width supported by the receiving fax terminal, and the page width in the file to be transmitted.

PRIenabled
Type

DWORD

Units

None.

Default Value

NFX_NO

Allowed Values

NFX_YES or NFX_NO

Description

Controls the ability of the transmitting fax terminal to send a Procedure Interrupt signal. When this parameter is set to NFX_YES, a Procedure Interrupt (PRI-EOP) will be sent to the called fax terminal after the last document in the transmit queue has been transmitted with nfxSendFax. This parameter has no effect when nfxAnswerFaxPoll is used. This parameter has no effect when polling is used with nfxSendFax.

resolution
Type

DWORD

Units

None.

Default Value

NFX_RESOLUTION_HIGH

Allowed Values

NFX_RESOLUTION_HIGH, NFX_RESOLUTION_LOW, NFX_RESOLUTION_SUPER_HIGH

Description

Limits the maximum resolution of fax images to be transmitted. The actual resolution used depends on the value of this parameter, the resolution supported by the receiving fax terminal, and the image resolution in the file to be transmitted.

retrainaction
Type

DWORD

Units

None.

Default Value

NFX_RTN_NEXT_PAGE

Allowed Values

NFX_RTN_NEXT_PAGE or NFX_RTN_REPEAT_PAGE

Description

Specifies the action to be taken when receiver indicates that a page with too many bad lines was received. If the value is NFX_RTN_NEXT_PAGE, the next page in the TIFF-F file will be transmitted. If the value is NFX_RTN_REPEAT_PAGE, the last page will be retransmitted.

SID
Type

char

Units

None.

Default Value

NULL

Allowed Values

A character string of 0 to 20 characters in length.

Description

Specifies the subscriber ID to be used when transmitting. The T.30 protocol recommends that the telephone number of the transmitting fax terminal is inserted in the SID field. In the US, the FCC requires that the telephone number be used in the SID field when transmitting faxes. The T.30 protocol specifies that the SID string contain only the digits 0 - 9, spaces, and [.] or [-].

threshold
Type

INT32

Units

tenths of dBm

Default Value

-430

Allowed Values

- 350 to -500

Description

Controls the lowest signal level to be accepted by NaturalFax as a receiver. -430 corresponds to a minimum signal level of -43 dBm. It is used in NFX_TRANSMIT_PARMS to control the receive level during a polling operation.

timeout
Type

DWORD

Units

seconds

Default Value

30

Allowed Values

0 - 120

Description

Specifies the maximum time for transmitter to continue sending the optional CNG tone and waiting to receive a CED tone from the receiving fax terminal. timeout is measured in units of seconds. If a CED tone is not detected before this time has expired, the NaturalFax transmitter will cancel the fax operation.

useCNG
Type

DWORD

Units

None.

Default Value

NFX_YES

Allowed Values

NFX_YES, NFX_NO

Description

Controls whether a CNG tone is transmitted during call establishment (Phase A of the T.30 protocol).

useECM
Type

DWORD

Units

None.

Default Value

NFX_YES

Allowed Values

NFX_YES, NFX_NO

Description

Controls whether the transmitter should use error correction mode (ECM) when it is available from the receiver. If set to NFX_NO, ECM will be disabled. If set to NFX_YES, ECM will be used if it is supported by the receiver.

NFX_RECEIVE_PARMS

The NFX_RECEIVE_PARMS structure controls the behavior of fax reception, including characteristics such as the maximum data rate and the resolution that will be accepted by the receiving fax terminal.

Dependent Functions

Related Data Structure

typedef struct 
{
  DWORD size;   
  DWORD modemtype;      /* 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, or            */
       /* NFX_ENCODE_MMR            */
  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;

NFX_RECEIVE_PARMS Structure Fields

The NFX_RECEIVE_PARMS structure contains the following fields:

badlineaction

Type

DWORD

Units

None.

Default Value

NFX_BAD_LINE_ACTION_REPT

Allowed Values

NFX_BAD_LINE_ACTION_NONE, NFX_BAD_LINE_ACTION_DROP, NFX_BAD_LINE_ACTION_REPT, NFX_BAD_LINE_ACTION_TICK

Description

Specifies the action that the receiving fax terminal takes upon receiving a bad line of image data. NFX_BAD_LINE_ACTION_NONE causes the bad line to be stored in the image file. NFX_BAD_LINE_ACTION_REPT repeats the previous line of image data. NFX_BAD_LINE_ACTION_DROP discards the line. NFX_BAD_LINE_ACTION_TICK adds a blank line with a tick mark (horizontal line) in both margins.

encoding

Type

DWORD

Units

None.

Default Value

NFX_ENCODE_1D

Allowed Values

NFX_ENCODE_1D, NFX_ENCODE_2D, or NFX_ENCODE_MMR

Description

Specifies the maximum image encoding format capabilities to be advertised when receiving. Setting encoding to NFX_ENCODE_1D ensures that all files will be stored in a format supported by all Group 3 fax terminals. useECM must be set to NFX_YES to use NFX_ENCODE_MMR.

level

Type

INT32

Units

tenths of dBm

Default Value

-135

Allowed Values

-150 to - 60

Description

Specifies the transmission level, -150 corresponds to -15 dBm, -60 corresponds to -6 dBm.

lineerrors

Type

DWORD

Units

count

Default Value

5

Allowed Values

0 - 100

Description

Sets a threshold for bad lines, expressed as a percentage of lines received. If the percent of bad lines is above this threshold, the receiver will request renegotiation with the transmitter by sending a RTN. If this parameter is set to 100, NaturalFax will never request renegotiation.

minrate

Type

DWORD

Units

bps

Default Value

NFX_BIT_RATE_2400

Allowed Values

NFX_BIT_RATE_9600, NFX_BIT_RATE_7200, NFX_BIT_RATE_4800, or NFX_BIT_RATE_2400

Description

Specifies the minimum bps rate to which the receiving fax terminal can negotiate. This parameter can be used to limit the range of rates used. NFX_BIT_RATE_2400 and NFX_BIT_RATE_4800 specify the V.27ter modems at 2400 and 4800 bps, respectively. NFX_BIT_RATE_7200 and NFX_BIT_RATE_9600 specify the V.29 modems at 7200 and 9600 bps.

modemtype

Type

DWORD

Units

None.

Default Value

NFX_MODEM_TYPE_V29

Allowed Values

NFX_MODEM_TYPE_V29, NFX_MODEM_TYPE_V27

Description

Allows the user to specify the maximum modem capabilities that will be advertised when receiving a fax. Specifying a preferred modem sets an upper limit on the set of modems NaturalFax will advertise.

The following modems support the following rates of data transmission:

· V.27 ter supports 2400 and 4800 bps

· V.29 supports 7200 and 9600 bps

NSF

Type

BYTE

Units

bytes

Default Value

NULL

Allowed Values

A byte array from 0 - 54 bytes in length.

Description

Assigns the value to be used in the Non-Standard Facilities frame when receiving a fax.

NSFlength

Type

DWORD

Units

bytes

Default Value

0

Allowed Values

0 - 54

Description

Specifies the length of the NSF field given in NFX_RECEIVE_PARMS.NSF. If this parameter is non-zero, the value in NSF will be used when negotiating with the remote fax terminal.

pollingenabled

Type

DWORD

Units

None.

Default Value

NFX_NO

Allowed Values

NFX_YES or NFX_NO

Description

Specifies whether the receiver advertises the ability to respond to a poll request from the transmitting fax terminal.

resolution

Type

DWORD

Units

None.

Default Value

NFX_RESOLUTION_HIGH

Allowed Values

NFX_RESOLUTION_HIGH, NFX_RESOLUTION_LOW, NFX_RESOLUTION_SUPER_HIGH

Description

Specifies the maximum resolution to be advertised by receiving fax terminal.

SID

Type

char

Units

None.

Default Value

NULL (empty string)

Allowed Values

A character string from 0 to 20 characters in length

Description

Specifies the subscriber ID to be used when transmitting. The T.30 protocol recommends that the telephone number of the transmitting fax terminal is inserted in the SID field. In the US, the FCC requires that the telephone number be used in the SID field when transmitting faxes. The T.30 protocol specifies that the SID string contain only the digits 0 - 9, spaces, and [.] or [-].

threshold

Type

INT32

Units

tenths of dBm

Default Value

-430

Allowed Values

- 350 to -500

Description

Controls the lowest signal level to be accepted by NaturalFax as a receiver. -430 corresponds to a minimum signal level of -43 dBm.

useECM

Type

DWORD

Units

None.

Default Value

NFX_YES

Allowed Values

NFX_YES, NFX_NO

Description

Controls whether NaturalFax will advertise error correction mode (ECM) capabilities as a receiver. If set to NFX_NO, ECM will not be advertised.

NFX_DOC_PARMS

The NFX_DOC_PARMS structure specifies details about each document to be enqueued, including encoding format and page width.

Dependent Functions

nfxEnqueueDoc

Related Data Structures

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_DOC_PARMS Structure Fields

The NFX_DOC_PARMS structure contains the following fields:

encoding

Type

DWORD

Units

None.

Default Value

NFX_ENCODE_1D

Allowed Values

NFX_ENCODE_1D, NFX_ENCODE_2D, or NFX_ENCODE_MMR

Description

Specifies the encoding format of specified document for the receiving fax terminal only. Encoding is used to specify how to store the received document when OTF conversions are enabled. This parameter has no effect during fax transmission, or when the OTF mode is set to NFX_OTF_NEVER.

pagewidth

Type

DWORD

Units

None.

Default Value

NFX_PAGE_WIDTH_A4

Allowed Values

NFX_PAGE_WIDTH_A4, NFX_PAGE_WIDTH_B4, NFX_PAGE_WIDTH_A3

Description

Specifies the page width of the designated document. Page width specifies how to store the received document when OTF conversions are enabled. This parameter has no effect during transmit

resolution

Type

DWORD

Units

None.

Default Value

NFX_RESOLUTION_HIGH

Allowed Values

NFX_RESOLUTION_HIGH, NFX_RESOLUTION_LOW, NFX_RESOLUTION_SUPER_HIGH

Description

Specifies the resolution of designated document for the receiving fax terminal only. Resolution is used to specify how to store the received document when OTF conversions are enabled. This parameter has no effect during transmit.

NFX_CONVERT_PARMS

The NFX_CONVERT_PARMS structure specifies attributes which are used by nfxConvertFileDirect.

Dependent Functions

nfxConvertFileDirect

Related Data Structures

typedef struct 
{
  DWORD size;
  DWORD type;     /* NFX_TIFF_F or NFX_TIFF_BI           */
  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 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;

NFX_CONVERT_PARMS Structure Fields

The NFX_CONVERT_PARMS structure contains the following fields:

badlineaction

Type

DWORD

Units

None.

Default Value

NFX_BAD_LINE_ACTION_REPT

Allowed Values

NFX_BAD_LINE_ACTION_REPT, NFX_BAD_LINE_ACTION_DROP, or NFX_BAD_LINE_ACTION_TICK

Description

Specifies how bad lines that are discovered in the input file are to appear in the output file. The default, NFX_BAD_LINE_ACTION_REPT, is to repeat the picture elements of the nearest previous good line. For NFX_BAD_LINE_ACTION_DROP, the bad line is eliminated from the destination file. For NFX_BAD_LINE_ACTION_TICK, the bad line is replaced by a blank line with a short black mark at either end.

When the source file has 2D encoding, an error in a single line may cause up to three subsequent lines to be considered "bad."

encoding

Type

DWORD

Units

None.

Default Value

NFX_ENCODE_1D

Allowed Values

NFX_ENCODE_1D, NFX_ENCODE_2D or NFX_ENCODE_MMR

Description

Specifies the encoding of the data to be stored in the output file. The input file data may be in 1D, 2D, or MMR encoding. Note that the encoding affects the size of image data only; it does not affect the appearance of the image.

pagewidth

Type

DWORD

Units

None.

Default Value

NFX_PAGE_WIDTH_A4

Allowed Values

NFX_PAGE_WIDTH_A4, NFX_PAGE_WIDTH_B4, or NFX_PAGE_WIDTH_A3

Description

Specifies the page width of the data to be stored in the output file. The input file data may have any of the allowed page widths. Note that the number of picture elements (pels) per line is 1728, 2048, and 2432 for NFX_PAGE_WIDTH_A4, NFX_PAGE_WIDTH_B4 and NFX_PAGE_WIDTH_A3, respectively. All are packed with the resolution of 200 picture elements per inch. Converting to a narrower page results in shrinking each line. Converting to a wider page results in padding the right side of the page with blank space.

resolution

Type

DWORD

Units

None.

Default Value

NFX_RESOLUTION_LOW

Allowed Values

NFX_RESOLUTION_LOW, NFX_RESOLUTION_HIGH, or NFX_RESOLUTION_SUPER_HIGH

Description

Specifies the vertical resolution of the data to be stored in the output file. The input file data may have any of the allowed resolutions. The resolution is 3.85, 7.7, and 15.4 scan lines per millimeter for NFX_RESOLUTION_LOW, NFX_RESOLUTION_HIGH, and NFX_RESOLUTION_SUPER_HIGH, respectively. Note that the horizontal resolution of the data is the same for NFX_RESOLUTION_LOW, NFX_RESOLUTION_HIGH, and NFX_RESOLUTION_SUPER_HIGH. The image appearance will be affected by a change in resolution.

type

Type

DWORD

Units

None.

Default Value

NFX_TIFF_F

Allowed Values

NFX_TIFF_F

Description

Specifies the overall format of the input file. This release of NaturalFax supports the TIFF-F format.



(Page 1 of 1 in this chapter)


tech_support@nmss.com
Copyright © 1998, Natural MicroSystems, Inc. All rights reserved.