nfxCheckTIFF

Verifies that the specified file is in TIFF-F format, and analyzes the attributes of the TIFF-F or TIFF-S file.

Prototype

DWORD nfxCheckTIFF ( CTAHD ctahd, char *input_file_name, DWORD *number_of_pages, DWORD tracked_pages, NFX_CHECK_STATUS *page_array)

Argument

Description

ctahd

Context handle returned by ctaCreateContext.

input_file_name

Pointer to the name of the file to check for TIFF-F or TIFF-S format.

number_of_pages

Pointer to the location that receives the number of pages in the input file.

tracked_pages

Number of pages to be reported in the array of NFX_CHECK_STATUS structures.

page_array

Pointer to an array of NFX_CHECK_STATUS structures. The count of entries in the array equals the value for tracked_pages. The NFX_CHECK_STATUS 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,            */
                      /* NFX_ENCODE_MMR, or NFX_ENCODE_TIFF_S     */
  DWORD pagewidth;    /* NFX_PAGE_WIDTH_A4, 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;

Return values

Return value

Description

SUCCESS

No bad lines were found.

CTAERR_BAD_ARGUMENT

Invalid function argument passed.

CTAERR_INVALID_CTAHD

The specified context handle is invalid.

NFXERR_BAD_FILE_FORMAT

The specified file is not in TIFF-F or TIFF-S format.

NFXERR_CHECK_BAD_LINES

The specified file has at least one bad line, but can still be transmitted with NaturalFax.

NFXERR_CHECK_DIFF_ATTRIB

All pages in the specified file do not have the same attributes. The file may not be transmitted by NaturalFax, but the status information returned by nfxCheckTIFF is valid.

Events

None.

Details

NaturalFax can transmit files in TIFF-F and TIFF-S format. nfxCheckTIFF reads and analyzes a specified file. It then stores the attributes of each page in a separate NFX_CHECK_STATUS structure in a returned array of NFX_CHECK_STATUS structures. The function fills in one structure per page until there are no more structures. If a pointer to page_array is not passed to nfxCheckTIFF, the information is not stored. If the number of pages in the document is greater than the value of tracked_pages, the additional page information is not stored, but is still used to determine the return value for the function.

If the file analyzed by nfxCheckTIFF is a TIFF-S file, the reported attributes are 1D encoding, LOW resolution, and A4 page width. TIFF-S is not explicitly stated, and TIFF-S compliance is not verified.

If there is a problem in the TIFF-F file, nfxCheckTIFF returns NFXERR_CHECK_BAD_LINES, but still produces a valid NFX_CHECK_STATUS structure array. Use this array to examine the page attributes to find any bad lines. The application can call nfxConvertFileDirect to remove the bad lines.

NaturalFax can transmit a file with bad lines.

When nfxCheckTIFF encounters a problem before it fills the array, it returns an error code other than NFXERR_CHECK_BAD_LINES or NFXERR_CHECK_DIFF_ATTRIB. In these cases, the information returned in the NFX_CHECK_STATUS structures may be incomplete.

Note: You must continue processing events during an active fax session. Make sure that file I/O intensive operations such as TIFF-F format verification do not interfere with the handling of events and cause the fax session to time out. The application should process events within three seconds.

Refer to Performing offline image conversion for more information.

See also

nfxConvertFileDirect