Version

Appendix B

NaturalFax Data Structures

About NaturalFax Structures

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

About NaturalFax Structures

NaturalFax stores system parameters, document status, and fax session status in its data structures. 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.
NaturalFax uses data structures to specify the behavior of fax functions. Natural 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. You can fill in and pass a parameter structure in the function call, or accept the default parameter values by passing a NULL pointer.
The following Natural Access functions obtain or modify parameter information:

ctaGetParmByName retrieves a single field for a given parameter name.

ctaSetParmByName modifies a single field for a given parameter name.

ctaGetParmInfo retrieves a parameter field definition.

ctaGetParms returns parameter values for a given parameter structure.

ctaRefreshParms resets the values of all context parameters on a context to the global defaults.
For more information about parameter management in Natural Access, see the Natural Access Developer's Reference Manual.

Parameter Structures

NFX_TRANSMIT_PARMS

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

NFX_TRANSMIT_PARMS

Dependent Function(s): nfxAnswerFaxPoll, nfxSendFax

Field name

Type

Default

Units

Description

addheader

DWORD

NFX_YES

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
· NFX_NO
· NFX_CUSTOM
For information on using NFX_CUSTOM, see custom_header.

custom_header

char

None

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 by using C style format strings:
· %d Date/time
· %p Page number
· %P Total number of pages in this fax

encoding

DWORD

NFX_ENCODE_1D

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. useECM must be set to NFX_YES to use NFX_ENCODE_MMR.
Values are
· NFX_ENCODE_1D
· NFX_ENCODE_2D
· NFX_ENCODE_MMR

ForceRate

DWORD

NFX_NO

None

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

level

INT32

-135

tenths of dBm

The transmission level. Values are -150 to - 60. -150 corresponds to -15 dBm,
-60 corresponds to -6 dBm.

minrate

DWORD

NFX_BIT_RATE_
2400

bps

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

modemtype

DWORD

NFX_MODEM_
TYPE_V17

None

The preferred modem for fax transmissions. Specifying a preferred modem sets an upper limit on the set of modems 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 bps
· V.29 supports 7200 and 9600 bps
· V.27ter supports 2400 and 4800 bits per second (bps)
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

NSF

BYTE

NULL

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.

NSFlength

DWORD

0

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 - 54.

OTFmode

DWORD

NFX_OTF_NEVER

None

When to perform on-the-fly conversion during a fax transmit operation. Values are
· NFX_OTF_NEVER to disable on-the-fly conversion.
· 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 details on format conversion, see Image Conversion During Fax Transmission in Chapter 3.

pagewidth

DWORD

NFX_PAGE_
WIDTH_A4

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
· NFX_PAGE_WIDTH_B4
· NFX_PAGE_WIDTH_A3

PRIenabled

DWORD

NFX_NO

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.

resolution

DWORD

NFX_RESOLUTION_HIGH

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
· NFX_RESOLUTION_LOW
· NFX_RESOLUTION_SUPER_HIGH

retrainaction

DWORD

NFX_RTN_NEXT_
PAGE

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.
· NFX_RTN_REPEAT_PAGE: the last page is retransmitted.

SID

char

NULL

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 [-].

SUB

char

NULL

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 #.

threshold

N/A

N/A

N/A

This parameter is not used.

timeout

DWORD

35

Seconds

The maximum allowed time for a transmitter to continue sending the CNG tone while waiting to receive a CED tone from the receiving fax terminal, measured in units of seconds. If a CED tone is not detected before this time has expired, the NaturalFax transmitter cancels the fax operation. Values are 10 - 120.
Changing this parameter makes your application non-compliant with phase A of the T.30 protocol, and greatly compromises fax machine compatibility. Use extreme caution when changing this parameter.

txrate

DWORD

NFX_BIT_RATE_
14400

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

useCNG

DWORD

NFX_YES

None

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

useECM

DWORD

NFX_NO

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.
· NFX_YES: ECM is used if supported by the receiver.

useSUBADD

DWORD

NFX_NO

None

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

NFX_TRANSMIT_PARMS
Dependent Function(s): nfxAnswerFaxPoll, nfxSendFax
Field name	Type	Default	Units	Description
addheader	DWORD	NFX_YES	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 · NFX_NO · NFX_CUSTOM For information on using NFX_CUSTOM, see custom_header.
custom_header	char	None	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 by using C style format strings: · %d Date/time · %p Page number · %P Total number of pages in this fax
encoding	DWORD	NFX_ENCODE_1D	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. useECM must be set to NFX_YES to use NFX_ENCODE_MMR. Values are · NFX_ENCODE_1D · NFX_ENCODE_2D · NFX_ENCODE_MMR
ForceRate	DWORD	NFX_NO	None	If ForceRate is set to NFX_YES, then NFX negotiates the transmission protocol starting with the specified modem type and rate, rather than the default V.17 14400. During the negotiation and training, NFX can fall down to a lower modem type and rate, but not to a modem rate lower than the specified minimum rate.
level	INT32	-135	tenths of dBm	The transmission level. Values are -150 to - 60. -150 corresponds to -15 dBm, -60 corresponds to -6 dBm.
minrate	DWORD	NFX_BIT_RATE_ 2400	bps	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
modemtype	DWORD	NFX_MODEM_ TYPE_V17	None	The preferred modem for fax transmissions. Specifying a preferred modem sets an upper limit on the set of modems 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 bps · V.29 supports 7200 and 9600 bps · V.27ter supports 2400 and 4800 bits per second (bps) 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
NSF	BYTE	NULL	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.
NSFlength	DWORD	0	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 - 54.
OTFmode	DWORD	NFX_OTF_NEVER	None	When to perform on-the-fly conversion during a fax transmit operation. Values are · NFX_OTF_NEVER to disable on-the-fly conversion. · 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 details on format conversion, see Image Conversion During Fax Transmission in Chapter 3.
pagewidth	DWORD	NFX_PAGE_ WIDTH_A4	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 · NFX_PAGE_WIDTH_B4 · NFX_PAGE_WIDTH_A3
PRIenabled	DWORD	NFX_NO	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.
resolution	DWORD	NFX_RESOLUTION_HIGH	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 · NFX_RESOLUTION_LOW · NFX_RESOLUTION_SUPER_HIGH
retrainaction	DWORD	NFX_RTN_NEXT_ PAGE	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. · NFX_RTN_REPEAT_PAGE: the last page is retransmitted.
SID	char	NULL	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 [-].
SUB	char	NULL	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 #.
threshold	N/A	N/A	N/A	This parameter is not used.
timeout	DWORD	35	Seconds	The maximum allowed time for a transmitter to continue sending the CNG tone while waiting to receive a CED tone from the receiving fax terminal, measured in units of seconds. If a CED tone is not detected before this time has expired, the NaturalFax transmitter cancels the fax operation. Values are 10 - 120. Changing this parameter makes your application non-compliant with phase A of the T.30 protocol, and greatly compromises fax machine compatibility. Use extreme caution when changing this parameter.
txrate	DWORD	NFX_BIT_RATE_ 14400	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
useCNG	DWORD	NFX_YES	None	Controls whether a CNG tone is transmitted during call establishment (Phase A of the T.30 protocol). Values are · NFX_YES · NFX_NO
useECM	DWORD	NFX_NO	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. · NFX_YES: ECM is used if supported by the receiver.
useSUBADD	DWORD	NFX_NO	None	Controls whether a SUB is transmitted during negotiation (Phase B of the T.30 protocol). Values are · NFX_YES · NFX_NO

NFX_RECEIVE_PARMS

The NFX_RECEIVE_PARMS structure controls the behavior of fax reception, including the maximum data rate and the resolution accepted by the receiving fax terminal.

NFX_RECEIVE_PARMS

Dependent Function(s): nfxReceiveFax, nfxSendFax

Field name

Type

Default

Units

Description

badlineaction

DWORD

NFX_BAD_LINE_
ACTION_REPT

None

The action that the receiving fax terminal takes upon receiving a bad line of image data. Values are
· 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

DWORD

NFX_ENCODE_1D

None

The maximum image encoding format capabilities to be advertised when receiving. 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.
NFX_ENCODE_TIFF_S causes the output file to be written using the TIFF-S specification. Values for the encoding, resolution and pagewidth fields are overwritten with TIFF-S defaults of 1D encoding, low resolution, and A4 pagewidth.

level

INT32

-135

tenths of dBm

The transmission level. Values are -150 to - 60. -150 corresponds to -15 dBm, -60 corresponds to -6 dBm.

lineerrors

DWORD

5

count

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

minrate

DWORD

NFX_BIT_RATE_
2400

bps

The minimum bps rate to which the receiving fax terminal can negotiate. This parameter can be used to limit the range of rates used.
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

modemtype

DWORD

NFX_MODEM_
TYPE_V29

None

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. AG, CG, and QX boards are capable of V.17 receive. AG Quad boards are not capable of V.17 receive.
Modems support the following rates of data transmission:
· V.27 ter supports 2400 and 4800 bps.
· V.29 supports 7200 and 9600 bps.
· V.17 supports 14400, 12000, 9600, and 7200 bps.

NSF

BYTE

NULL

bytes

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

NSFlength

DWORD

0

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 - 54.

OTFmode

DWORD

NFX_OTF_NEVER

None

When to perform on-the-fly conversion during a fax receive operation. When receiving a fax, set to NFX_OTF_NEVER or NFX_OTF_ONLY_IF_FAIL to disable on-the-fly conversion and minimize CPU usage. Set to NFX_OTF_ALWAYS to always perform a conversion.
For details on format conversion, see Image Conversion During Fax Reception.

pollingenabled

DWORD

NFX_NO

None

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

resolution

DWORD

NFX_RESOLUTION_HIGH

None

The maximum resolution to be advertised by receiving fax terminal.
Values are
· NFX_RESOLUTION_HIGH
· NFX_RESOLUTION_LOW
· NFX_RESOLUTION_SUPER_HIGH

SID

char

NULL

None

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

SUB

char

NULL

None

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

threshold

INT32

-430

tenths of dBm

The lowest signal level to be accepted by NaturalFax as a receiver. Values are -300 to -430. -430 corresponds to a minimum signal level of -43 dBm.

useECM

DWORD

NFX_NO

None

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

useSUBADD

DWORD

NFX_YES

None

Controls whether NaturalFax advertises SUB (sub-addressing) capabilities as a receiver. If set to NFX_NO, SUB is not advertised.

NFX_RECEIVE_PARMS
Dependent Function(s): nfxReceiveFax, nfxSendFax
Field name	Type	Default	Units	Description
badlineaction	DWORD	NFX_BAD_LINE_ ACTION_REPT	None	The action that the receiving fax terminal takes upon receiving a bad line of image data. Values are · 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	DWORD	NFX_ENCODE_1D	None	The maximum image encoding format capabilities to be advertised when receiving. 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. NFX_ENCODE_TIFF_S causes the output file to be written using the TIFF-S specification. Values for the encoding, resolution and pagewidth fields are overwritten with TIFF-S defaults of 1D encoding, low resolution, and A4 pagewidth.
level	INT32	-135	tenths of dBm	The transmission level. Values are -150 to - 60. -150 corresponds to -15 dBm, -60 corresponds to -6 dBm.
lineerrors	DWORD	5	count	The threshold for bad lines, expressed as a percentage of lines received. If the percent of bad lines is above this threshold, the receiver requests renegotiation with the transmitter by sending a RTN. If this parameter is set to 100, NaturalFax will never request renegotiation. Values are 0 - 100.
minrate	DWORD	NFX_BIT_RATE_ 2400	bps	The minimum bps rate to which the receiving fax terminal can negotiate. This parameter can be used to limit the range of rates used. 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
modemtype	DWORD	NFX_MODEM_ TYPE_V29	None	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. AG, CG, and QX boards are capable of V.17 receive. AG Quad boards are not capable of V.17 receive. Modems support the following rates of data transmission: · V.27 ter supports 2400 and 4800 bps. · V.29 supports 7200 and 9600 bps. · V.17 supports 14400, 12000, 9600, and 7200 bps.
NSF	BYTE	NULL	bytes	The value to be used in the non-standard facilities frame when receiving a fax. Values are a byte array between 0 and 54 bytes in length.
NSFlength	DWORD	0	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 - 54.
OTFmode	DWORD	NFX_OTF_NEVER	None	When to perform on-the-fly conversion during a fax receive operation. When receiving a fax, set to NFX_OTF_NEVER or NFX_OTF_ONLY_IF_FAIL to disable on-the-fly conversion and minimize CPU usage. Set to NFX_OTF_ALWAYS to always perform a conversion. For details on format conversion, see Image Conversion During Fax Reception.
pollingenabled	DWORD	NFX_NO	None	Whether the receiver advertises the ability to respond to a poll request from the transmitting fax terminal.
resolution	DWORD	NFX_RESOLUTION_HIGH	None	The maximum resolution to be advertised by receiving fax terminal. Values are · NFX_RESOLUTION_HIGH · NFX_RESOLUTION_LOW · NFX_RESOLUTION_SUPER_HIGH
SID	char	NULL	None	The subscriber ID to be used when receiving. The T.30 protocol recommends using the telephone number of the transmitting fax terminal. In the US, the FCC requires using the telephone number in the SID field when transmitting faxes. Values are a character string of 0 to 20 characters in length. The T.30 protocol allows only the digits 0 - 9, spaces, and [.] or [-].
SUB	char	NULL	None	The sub-address string to be used when receiving. Values are a character string of 0 to 20 characters in length. The T.30 protocol allows only the digits 0 - 9, spaces, and * or #.
threshold	INT32	-430	tenths of dBm	The lowest signal level to be accepted by NaturalFax as a receiver. Values are -300 to -430. -430 corresponds to a minimum signal level of -43 dBm.
useECM	DWORD	NFX_NO	None	Controls whether NaturalFax advertises error correction mode (ECM) capabilities as a receiver. If set to NFX_NO, ECM is not advertised.
useSUBADD	DWORD	NFX_YES	None	Controls whether NaturalFax advertises SUB (sub-addressing) capabilities as a receiver. If set to NFX_NO, SUB is not advertised.

NFX_DOC_PARMS

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

NFX_DOC_PARMS

Dependent Function(s): nfxEnqueueDoc

Field name

Type

Default

Units

Description

encoding

DWORD

NFX_ENCODE_1D

None

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. Values are
· NFX_ENCODE_1D
· NFX_ENCODE_2D
· NFX_ENCODE_MMR

pagewidth

DWORD

NFX_PAGE_
WIDTH_A4

None

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. Values are
· NFX_PAGE_WIDTH_A4
· NFX_PAGE_WIDTH_B4
· NFX_PAGE_WIDTH_A3

resolution

DWORD

NFX_RESOLUTION_HIGH

None

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.
Values are
· NFX_RESOLUTION_HIGH
· NFX_RESOLUTION_LOW
· NFX_RESOLUTION_SUPER_HIGH

NFX_DOC_PARMS
Dependent Function(s): nfxEnqueueDoc
Field name	Type	Default	Units	Description
encoding	DWORD	NFX_ENCODE_1D	None	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. Values are · NFX_ENCODE_1D · NFX_ENCODE_2D · NFX_ENCODE_MMR
pagewidth	DWORD	NFX_PAGE_ WIDTH_A4	None	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. Values are · NFX_PAGE_WIDTH_A4 · NFX_PAGE_WIDTH_B4 · NFX_PAGE_WIDTH_A3
resolution	DWORD	NFX_RESOLUTION_HIGH	None	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. Values are · NFX_RESOLUTION_HIGH · NFX_RESOLUTION_LOW · NFX_RESOLUTION_SUPER_HIGH

NFX_CONVERT_PARMS

The NFX_CONVERT_PARMS structure specifies attributes that are used by nfxConvertFileDirect.

NFX_CONVERT_PARMS

Dependent Function(s): nfxConvertFileDirect

Field name

Type

Default

Units

Description

badlineaction

DWORD

NFX_BAD_LINE_
ACTION_REPT

None

How bad lines that are discovered in the input file are to appear in the output file. NFX_BAD_LINE_ACTION_REPT repeats the picture elements of the nearest previous good line. NFX_BAD_LINE_ACTION_DROP eliminates the bad line from the destination file. NFX_BAD_LINE_ACTION_TICK replaces the bad line with 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

DWORD

NFX_ENCODE_1D

None

The encoding of the data to be stored in the output file. The input file data may be in 1D, 2D, or MMR encoding.
NFX_ENCODE_TIFF_S writes the output file according to the TIFF-S specification. Values will be overridden to 1D encoding, low resolution, and A4 pagewidth.
Note that the encoding affects the size of image data only; it does not affect the appearance of the image. Values are
· NFX_ENCODE_1D
· NFX_ENCODE_2D
· NFX_ENCODE_MMR
· NFX_ENCODE_TIFF_S

pagewidth

DWORD

NFX_PAGE_
WIDTH_A4

None

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. 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. Values are
· NFX_PAGE_WIDTH_A4
· NFX_PAGE_WIDTH_B4
· NFX_PAGE_WIDTH_A3

resolution

DWORD

NFX_RESOLUTION_LOW

None

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. The horizontal resolution of the data is the same for all values. The image appearance is affected by a change in resolution.

type

DWORD

NFX_TIFF_F

None

The overall format of the input file. NaturalFax supports the TIFF-F format. Specifying a value of NFX_TIFF_S has the same effect as specifying a value of NFX_ENCODE_TIFF_S in the encoding field.

NFX_CONVERT_PARMS
Dependent Function(s): nfxConvertFileDirect
Field name	Type	Default	Units	Description
badlineaction	DWORD	NFX_BAD_LINE_ ACTION_REPT	None	How bad lines that are discovered in the input file are to appear in the output file. NFX_BAD_LINE_ACTION_REPT repeats the picture elements of the nearest previous good line. NFX_BAD_LINE_ACTION_DROP eliminates the bad line from the destination file. NFX_BAD_LINE_ACTION_TICK replaces the bad line with 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	DWORD	NFX_ENCODE_1D	None	The encoding of the data to be stored in the output file. The input file data may be in 1D, 2D, or MMR encoding. NFX_ENCODE_TIFF_S writes the output file according to the TIFF-S specification. Values will be overridden to 1D encoding, low resolution, and A4 pagewidth. Note that the encoding affects the size of image data only; it does not affect the appearance of the image. Values are · NFX_ENCODE_1D · NFX_ENCODE_2D · NFX_ENCODE_MMR · NFX_ENCODE_TIFF_S
pagewidth	DWORD	NFX_PAGE_ WIDTH_A4	None	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. 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. Values are · NFX_PAGE_WIDTH_A4 · NFX_PAGE_WIDTH_B4 · NFX_PAGE_WIDTH_A3
resolution	DWORD	NFX_RESOLUTION_LOW	None	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. The horizontal resolution of the data is the same for all values. The image appearance is affected by a change in resolution.
type	DWORD	NFX_TIFF_F	None	The overall format of the input file. NaturalFax supports the TIFF-F format. Specifying a value of NFX_TIFF_S has the same effect as specifying a value of NFX_ENCODE_TIFF_S in the encoding field.

Status Structures

NaturalFax records the status of fax sessions and the status of each document processed during a fax session.

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. To view the structure definition, refer to the dependent function nfxGetSessionStatus.

NFX_DOC_STATUS

The NFX_DOC_STATUS structure stores the status of one document entry in a particular document queue. To view the structure definition, refer to the dependent function nfxGetDocStatus.

NFX_CHECK_STATUS

The NFX_CHECK_STATUS structure stores the status of the image format found on each page of a TIFF file. To view the structure definition, refer to the dependent function nfxCheckTIFF.

Version

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