NFX_TRANSMIT_PARMS

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

Dependent functions: nfxAnswerFaxPoll, nfxSendFax

Field name

Type

Units

Description

addheader

DWORD

None

Mandatory for applications running in countries under FCC or DoC jurisdiction. Indicates whether headers are added to the transmitted image data. NFX_YES creates a header that is a fixed ASCII string in the following format:

FROM transmit_SID Date Time Page N of M

Values are:

  • NFX_YES (default)

  • NFX_NO

  • NFX_CUSTOM

For information on using NFX_CUSTOM, see custom_header.

custom_header

char

ASCII characters

Adds a customized header of up to 80 ASCII characters. The custom header can include page number and the date and time for each page using C style format strings:

  • %d = Date/time string.

  • %p = Page number.

  • %P = Total number of pages in this fax.

  • %y = Current page number in fax session.

  • %Y = Total number of pages in all documents in queue.

Default: None

encoding

DWORD

None

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. The useECM parameter must be set to NFX_YES to use NFX_ENCODE_MMR.

Values are:

  • NFX_ENCODE_1D (default)

  • NFX_ENCODE_2D

  • NFX_ENCODE_MMR

ForceRate

DWORD

None

If ForceRate is set to NFX_YES, then NFX negotiates the transmission protocol starting with the specified modemtype and minrate, rather than the default V.17 14400. During negotiation and training, NFX can drop to a lower modemtype and minrate, but not to a modem rate lower than the specified minimum rate.

Default: NFX_NO

level

INT32

tenths of dBm

The transmission level. Values are -150 to - 60.

  • -150 corresponds to -15 dBm.

  • -60 corresponds to -6 dBm.

Default: -135

minrate

DWORD

b/s

The minimum allowed rate that NaturalFax selects for fax transmissions. Can be used to limit the range of rates used.

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

Values are:

  • NFX_BIT_RATE_14400

  • NFX_BIT_RATE_12000

  • NFX_BIT_RATE_9600

  • NFX_BIT_RATE_7200

  • NFX_BIT_RATE_4800

  • NFX_BIT_RATE_2400 (default)

modemtype

DWORD

None

The preferred modem for fax transmissions. Specifying a preferred modem sets an upper limit on the set of modems that NaturalFax considers when trying to match the receiving fax terminal's capabilities.

Modems support the following rates of data transmission:

  • V.17 supports 7200, 9600, 12,000, and 14,400 b/s

  • V.29 supports 7200 and 9600 b/s

  • V.27ter supports 2400 and 4800 b/s

If NaturalFax drops to a modem type that supports lower transmission rates, it attempts 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 that rate. If not, 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 attempts to use the modem that supports the next lowest transmission rate that is still at or above the minrate value.

Values are:

  • NFX_MODEM_TYPE_V27

  • NFX_MODEM_TYPE_V29

  • NFX_MODEM_TYPE_V17 (default)

NSF

BYTE

bytes

The value to be used in the non-standard facilities frame on transmit. Values are a byte array between 0 and 54 bytes in length.

Default: NULL

NSFlength

DWORD

bytes

The length of the NSF field given in TRANSMIT_PARMS.NSF. If this parameter is non-zero, the value in NSF is used when negotiating with the remote fax terminal. Values are 0 - 96.

Default: 0

OTFmode

DWORD

None

Specifies when to perform on-the-fly conversion during a fax transmit operation. Values are:

  • NFX_OTF_NEVER: To disable on-the-fly conversion (default).

  • NFX_OTF_ONLY_IF_FAIL: To perform format conversions only when fax negotiations would otherwise fail.

  • NFX_OTF_ALWAYS: To always perform a conversion.

For more information, refer to Image conversion during fax transmission.

pagewidth

DWORD

None

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. Values are:

  • NFX_PAGE_WIDTH_A4 (default)

  • NFX_PAGE_WIDTH_B4

  • NFX_PAGE_WIDTH_A3

PRIenabled

DWORD

None

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

Default: NFX_NO

resolution

DWORD

None

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. Values are:

  • NFX_RESOLUTION_HIGH (default)

  • NFX_RESOLUTION_LOW

  • NFX_RESOLUTION_SUPER_HIGH

retrainaction

DWORD

None

The action to be taken when receiver indicates that a page with too many bad lines was received. Values are:

  • NFX_RTN_NEXT_PAGE: The next page in the TIFF-F file is transmitted (default).

  • NFX_RTN_REPEAT_PAGE: The last page is retransmitted.

SID

char

None

The subscriber ID to be used when transmitting. The T.30 protocol recommends inserting the telephone number of the transmitting fax terminal in this field. In the US, the FCC requires using the telephone number in this field when transmitting faxes. Values are a character string of 0 to 20 characters in length. The T.30 protocol specifies a string of only digits 0 - 9, spaces, and [.] or [-].

Default: NULL

SUB

char

None

The sub-address string to be used when transmitting. Values are a character string of 0 to 20 characters in length. The T.30 protocol specifies a string of only the digits 0 - 9, spaces, and * or #.

Default: NULL

threshold

N/A

N/A

Do not modify.

timeout

DWORD

Seconds

The maximum allowed time for a transmitter to continue sending the CNG tone while waiting to receive a DIS tone from the receiving fax terminal. If a DIS tone is not detected before this time has expired, the NaturalFax transmitter cancels the fax operation. Values are 10 - 120.

Changing this parameter makes the application non-compliant with phase B of the T.30 protocol, and greatly compromises fax machine compatibility. Use extreme caution when changing this parameter.

Default: 35

txrate

DWORD

None

The preferred modem rate for the fax transmission. When the ForceRate flag is set to NFX_YES, NFX negotiates the transmission protocol starting with this modem rate. The parameter must be valid for the specified modem type. If an invalid txrate and modemtype combination is specified, the fax session terminates with a CTAERR_BAD_ARGUMENT error.

If a modem type and rate are specified but the receiver is not compatible with the specified rate, NFX negotiates down to a lower modem rate. NFX does not negotiate to a modem rate lower than the specified minrate. Values are:

  • NFX_BIT_RATE_2400

  • NFX_BIT_RATE_4800

  • NFX_BIT_RATE_7200

  • NFX_BIT_RATE_9600

  • NFX_BIT_RATE_12000

  • NFX_BIT_RATE_14400 (default)

useCNG

DWORD

None

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

  • NFX_YES (default)

  • NFX_NO

useECM

DWORD

None

Controls whether the transmitter should use error correction mode (ECM) when it is available from the receiver. Values are:

  • NFX_NO: ECM is disabled (default).

  • NFX_YES: ECM is used if supported by the receiver.

useSUBADD

DWORD

None

Controls whether a SUB is transmitted during negotiation (Phase B of the T.30 protocol). Values are:

  • NFX_YES

  • NFX_NO (default)