Function declarations and constants for FreeXL library. More...

Data Structures
struct	FreeXL_CellValue_str
	Container for a cell value. More...

Macros
#define	FREEXL_UNKNOWN 0
	query is not applicable, or information is not available

#define	FREEXL_CFBF_VER_3 3
	CFBF file is version 3.

#define	FREEXL_CFBF_VER_4 4
	CFBF file is version 4.

#define	FREEXL_CFBF_SECTOR_512 512
	CFBF file uses 512 byte sectors.

#define	FREEXL_CFBF_SECTOR_4096 4096
	CFBF file uses 4096 (4K) sectors.

#define	FREEXL_BIFF_VER_2 2
	BIFF file is version 2.

#define	FREEXL_BIFF_VER_3 3
	BIFF file is version 3.

#define	FREEXL_BIFF_VER_4 4
	BIFF file is version 4.

#define	FREEXL_BIFF_VER_5 5
	BIFF file is version 5.

#define	FREEXL_BIFF_VER_8 8
	BIFF file is version 9.

#define	FREEXL_BIFF_MAX_RECSZ_2080 2080
	Maximum BIFF record size is 2080 bytes.

#define	FREEXL_BIFF_MAX_RECSZ_8224 8224
	Maximum BIFF record size is 8224 bytes.

#define	FREEXL_BIFF_DATEMODE_1900 1900
	BIFF date mode starts at 1 Jan 1900.

#define	FREEXL_BIFF_DATEMODE_1904 1904
	BIFF date mode starts at 2 Jan 1904.

#define	FREEXL_BIFF_OBFUSCATED 3003
	BIFF file is password protected.

#define	FREEXL_BIFF_PLAIN 3004
	BIFF file is not password protected.

#define	FREEXL_BIFF_ASCII 0x016F
	BIFF file uses plain ASCII encoding.

#define	FREEXL_BIFF_CP437 0x01B5
	BIFF file uses CP437 (OEM US format) encoding.

#define	FREEXL_BIFF_CP720 0x02D0
	BIFF file uses CP720 (Arabic DOS format) encoding.

#define	FREEXL_BIFF_CP737 0x02E1
	BIFF file uses CP737 (Greek DOS format) encoding.

#define	FREEXL_BIFF_CP775 0x0307
	BIFF file uses CP775 (Baltic DOS format) encoding.

#define	FREEXL_BIFF_CP850 0x0352
	BIFF file uses CP850 (Western Europe DOS format) encoding.

#define	FREEXL_BIFF_CP852 0x0354
	BIFF file uses CP852 (Central Europe DOS format) encoding.

#define	FREEXL_BIFF_CP855 0x0357
	BIFF file uses CP855 (OEM Cyrillic format) encoding.

#define	FREEXL_BIFF_CP857 0x0359
	BIFF file uses CP857 (Turkish DOS format) encoding.

#define	FREEXL_BIFF_CP858 0x035A
	BIFF file uses CP858 (OEM Multiligual Latin 1 format) encoding.

#define	FREEXL_BIFF_CP860 0x035C
	BIFF file uses CP860 (Portuguese DOS format) encoding.

#define	FREEXL_BIFF_CP861 0x035D
	BIFF file uses CP861 (Icelandic DOS format) encoding.

#define	FREEXL_BIFF_CP862 0x035E
	BIFF file uses CP862 (Hebrew DOS format) encoding.

#define	FREEXL_BIFF_CP863 0x035F
	BIFF file uses CP863 (French Canadian DOS format) encoding.

#define	FREEXL_BIFF_CP864 0x0360
	BIFF file uses CP864 (Arabic DOS format) encoding.

#define	FREEXL_BIFF_CP865 0x0361
	BIFF file uses CP865 (Nordic DOS format) encoding.

#define	FREEXL_BIFF_CP866 0x0362
	BIFF file uses CP866 (Cyrillic DOS format) encoding.

#define	FREEXL_BIFF_CP869 0x0365
	BIFF file uses CP869 (Modern Greek DOS format) encoding.

#define	FREEXL_BIFF_CP874 0x036A
	BIFF file uses CP874 (Thai Windows format) encoding.

#define	FREEXL_BIFF_CP932 0x03A4
	BIFF file uses CP932 (Shift JIS format) encoding.

#define	FREEXL_BIFF_CP936 0x03A8
	BIFF file uses CP936 (Simplified Chinese GB2312 format) encoding.

#define	FREEXL_BIFF_CP949 0x03B5
	BIFF file uses CP949 (Korean) encoding.

#define	FREEXL_BIFF_CP950 0x03B6
	BIFF file uses CP950 (Traditional Chinese Big5 format) encoding.

#define	FREEXL_BIFF_UTF16LE 0x04B0
	BIFF file uses Unicode (UTF-16LE format) encoding.

#define	FREEXL_BIFF_CP1250 0x04E2
	BIFF file uses CP1250 (Central Europe Windows) encoding.

#define	FREEXL_BIFF_CP1251 0x04E3
	BIFF file uses CP1251 (Cyrillic Windows) encoding.

#define	FREEXL_BIFF_CP1252 0x04E4
	BIFF file uses CP1252 (Windows Latin 1) encoding.

#define	FREEXL_BIFF_CP1253 0x04E5
	BIFF file uses CP1252 (Windows Greek) encoding.

#define	FREEXL_BIFF_CP1254 0x04E6
	BIFF file uses CP1254 (Windows Turkish) encoding.

#define	FREEXL_BIFF_CP1255 0x04E7
	BIFF file uses CP1255 (Windows Hebrew) encoding.

#define	FREEXL_BIFF_CP1256 0x04E8
	BIFF file uses CP1256 (Windows Arabic) encoding.

#define	FREEXL_BIFF_CP1257 0x04E9
	BIFF file uses CP1257 (Windows Baltic) encoding.

#define	FREEXL_BIFF_CP1258 0x04EA
	BIFF file uses CP1258 (Windows Vietnamese) encoding.

#define	FREEXL_BIFF_CP1361 0x0551
	BIFF file uses CP1361 (Korean Johab) encoding.

#define	FREEXL_BIFF_MACROMAN 0x2710
	BIFF file uses Mac Roman encoding.

#define	FREEXL_CELL_NULL 101
	Cell has no value (empty cell)

#define	FREEXL_CELL_INT 102
	Cell contains an integer value.

#define	FREEXL_CELL_DOUBLE 103
	Cell contains a floating point number.

#define	FREEXL_CELL_TEXT 104
	Cell contains a text value.

#define	FREEXL_CELL_SST_TEXT 105
	Cell contains a reference to a Single String Table entry (BIFF8)

#define	FREEXL_CELL_DATE 106
	Cell contains a number intended to represent a date.

#define	FREEXL_CELL_DATETIME 107
	Cell contains a number intended to represent a date and time.

#define	FREEXL_CELL_TIME 108
	Cell contains a number intended to represent a time.

#define	FREEXL_CFBF_VERSION 32001
	Information query for CFBF version.

#define	FREEXL_CFBF_SECTOR_SIZE 32002
	Information query for CFBF sector size.

#define	FREEXL_CFBF_FAT_COUNT 32003
	Information query for CFBF FAT entry count.

#define	FREEXL_BIFF_VERSION 32005
	Information query for BIFF version.

#define	FREEXL_BIFF_MAX_RECSIZE 32006
	Information query for BIFF maximum record size.

#define	FREEXL_BIFF_DATEMODE 32007
	Information query for BIFF date mode.

#define	FREEXL_BIFF_PASSWORD 32008
	Information query for BIFF password protection state.

#define	FREEXL_BIFF_CODEPAGE 32009
	Information query for BIFF character encoding.

#define	FREEXL_BIFF_SHEET_COUNT 32010
	Information query for BIFF sheet count.

#define	FREEXL_BIFF_STRING_COUNT 32011
	Information query for BIFF Single String Table entry count (BIFF8)

#define	FREEXL_BIFF_FORMAT_COUNT 32012
	Information query for BIFF format count.

#define	FREEXL_BIFF_XF_COUNT 32013
	Information query for BIFF extended format count.

#define	FREEXL_OK 0
	No error, success.

#define	FREEXL_FILE_NOT_FOUND -1
	.xls file does not exist or is not accessible for reading

#define	FREEXL_NULL_HANDLE -2
	Null xls_handle argument.

#define	FREEXL_INVALID_HANDLE -3
	Invalid xls_handle argument.

#define	FREEXL_INSUFFICIENT_MEMORY -4
	some kind of memory allocation failure

#define	FREEXL_NULL_ARGUMENT -5
	an unexpected null argument

#define	FREEXL_INVALID_INFO_ARG -6
	invalid "what" parameter

#define	FREEXL_INVALID_CFBF_HEADER -7
	the .xls file does not contain a valid CFBF header

#define	FREEXL_CFBF_READ_ERROR -8
	Read error. More...

#define	FREEXL_CFBF_SEEK_ERROR -9
	Seek error. More...

#define	FREEXL_CFBF_INVALID_SIGNATURE -10
	The .xls file does contain a CFBF header, but the header is broken or corrupted in some way.

#define	FREEXL_CFBF_INVALID_SECTOR_SIZE -11
	The .xls file does contain a CFBF header, but the header is broken or corrupted in some way.

#define	FREEXL_CFBF_EMPTY_FAT_CHAIN -12
	The .xls file does contain a CFBF header, but the header is broken or corrupted in some way.

#define	FREEXL_CFBF_ILLEGAL_FAT_ENTRY -13
	The file contains an invalid File Allocation Table record.

#define	FREEXL_BIFF_INVALID_BOF -14
	The file contains an invalid BIFF format entry.

#define	FREEXL_BIFF_INVALID_SST -15
	The file contains an invalid Single String Table.

#define	FREEXL_BIFF_ILLEGAL_SST_INDEX -16
	The requested Single String Table entry is not available.

#define	FREEXL_BIFF_WORKBOOK_NOT_FOUND -17
	BIFF does not contain a valid workbook.

#define	FREEXL_BIFF_ILLEGAL_SHEET_INDEX -18
	The requested worksheet is not available in the workbook.

#define	FREEXL_BIFF_UNSELECTED_SHEET -19
	There is no currently active worksheet. More...

#define	FREEXL_INVALID_CHARACTER -20
	Charset conversion detected an illegal character (not within the declared charset)

#define	FREEXL_UNSUPPORTED_CHARSET -21
	The requested charset conversion is not available. More...

#define	FREEXL_ILLEGAL_CELL_ROW_COL -22
	The requested cell is outside the valid range for the sheet.

#define	FREEXL_ILLEGAL_RK_VALUE -23
	Conversion of the RK value failed. More...

#define	FREEXL_ILLEGAL_MULRK_VALUE -23
	Conversion of the MULRK value failed. More...

#define	FREEXL_INVALID_MINI_STREAM -24
	The MiniFAT stream is invalid. More...

#define	FREEXL_CFBF_ILLEGAL_MINI_FAT_ENTRY -25
	The MiniFAT stream contains an invalid entry. More...

#define	FREEXL_CRAFTED_FILE -26
	A severely corrupted file (may be purposely crafted for malicious purposes) has been detected. More...

Typedefs
typedef struct FreeXL_CellValue_str	FreeXL_CellValue
	Typedef for cell value structure. More...

Functions
FREEXL_DECLARE const char *	freexl_version (void)
	Return the current library version. More...

FREEXL_DECLARE int	freexl_open (const char path, const void *xls_handle)
	Open the .xls file, preparing for future functions. More...

FREEXL_DECLARE int	freexl_open_info (const char path, const void *xls_handle)
	Open the .xls file for metadata query only. More...

FREEXL_DECLARE int	freexl_close (const void *xls_handle)
	Close the .xls file and releasing any allocated resource. More...

FREEXL_DECLARE int	freexl_get_info (const void xls_handle, unsigned short what, unsigned int info)
	Query general information about the Workbook and Worksheets. More...

FREEXL_DECLARE int	freexl_get_worksheet_name (const void xls_handle, unsigned short sheet_index, const char *string)
	Query worksheet name. More...

FREEXL_DECLARE int	freexl_select_active_worksheet (const void *xls_handle, unsigned short sheet_index)
	Set the currently active worksheets. More...

FREEXL_DECLARE int	freexl_get_active_worksheet (const void xls_handle, unsigned short sheet_index)
	Query the currently active worksheet index. More...

FREEXL_DECLARE int	freexl_worksheet_dimensions (const void xls_handle, unsigned int rows, unsigned short *columns)
	Query worksheet dimensions. More...

FREEXL_DECLARE int	freexl_get_SST_string (const void xls_handle, unsigned short string_index, const char *string)
	Retrieve string entries from SST. More...

FREEXL_DECLARE int	freexl_get_FAT_entry (const void xls_handle, unsigned int sector_index, unsigned int next_sector_index)
	Retrieve FAT entries from FAT chain. More...

FREEXL_DECLARE int	freexl_get_cell_value (const void xls_handle, unsigned int row, unsigned short column, FreeXL_CellValue value)
	Retrieve individual cell values from the currently active worksheet. More...

Detailed Description

Function declarations and constants for FreeXL library.

Macro Definition Documentation

◆ FREEXL_BIFF_UNSELECTED_SHEET

#define FREEXL_BIFF_UNSELECTED_SHEET -19

There is no currently active worksheet.

Possibly a forgotten call to freexl_select_active_worksheet()

◆ FREEXL_CFBF_ILLEGAL_MINI_FAT_ENTRY

#define FREEXL_CFBF_ILLEGAL_MINI_FAT_ENTRY -25

The MiniFAT stream contains an invalid entry.

Possibly a corrupt file.

◆ FREEXL_CFBF_READ_ERROR

#define FREEXL_CFBF_READ_ERROR -8

Read error.

Usually indicates a corrupt or invalid .xls file

◆ FREEXL_CFBF_SEEK_ERROR

#define FREEXL_CFBF_SEEK_ERROR -9

Seek error.

Usually indicates a corrupt or invalid .xls file

◆ FREEXL_CRAFTED_FILE

#define FREEXL_CRAFTED_FILE -26

A severely corrupted file (may be purposely crafted for malicious purposes) has been detected.

◆ FREEXL_ILLEGAL_MULRK_VALUE

#define FREEXL_ILLEGAL_MULRK_VALUE -23

Conversion of the MULRK value failed.

Possibly a corrupt file or a bug in FreeXL.

◆ FREEXL_ILLEGAL_RK_VALUE

#define FREEXL_ILLEGAL_RK_VALUE -23

Conversion of the RK value failed.

Possibly a corrupt file or a bug in FreeXL.

◆ FREEXL_INVALID_MINI_STREAM

#define FREEXL_INVALID_MINI_STREAM -24

The MiniFAT stream is invalid.

Possibly a corrupt file.

◆ FREEXL_UNSUPPORTED_CHARSET

#define FREEXL_UNSUPPORTED_CHARSET -21

The requested charset conversion is not available.

Typedef Documentation

◆ FreeXL_CellValue

typedef struct FreeXL_CellValue_str FreeXL_CellValue

Typedef for cell value structure.

See also: FreeXL_CellValue_str

Function Documentation

◆ freexl_close()

FREEXL_DECLARE int freexl_close ( const void * xls_handle )

Close the .xls file and releasing any allocated resource.

Parameters

xls_handle the handle previously returned by freexl_open()

Returns: FREEXL_OK will be returned on success

Note: After calling freexl_close() any related resource will be released, and the handle will no longer be valid.

Examples: test_xl.c, and xl2sql.c.

◆ freexl_get_active_worksheet()

FREEXL_DECLARE int freexl_get_active_worksheet	(	const void *	xls_handle,
		unsigned short *	sheet_index
	)

Query the currently active worksheet index.

Parameters

xls_handle	the handle previously returned by freexl_open()
sheet_index	the index corresponding to the currently active Worksheet (return value)

Returns: FREEXL_OK will be returned on success

See also: freexl_select_active_worksheet() for how to select the worksheet

Examples: test_xl.c.

◆ freexl_get_cell_value()

FREEXL_DECLARE int freexl_get_cell_value	(	const void *	xls_handle,
		unsigned int	row,
		unsigned short	column,
		FreeXL_CellValue *	value
	)

Retrieve individual cell values from the currently active worksheet.

Parameters

xls_handle	the handle previously returned by freexl_open()
row	row number of the cell to query (zero base)
column	column number of the cell to query (zero base)
value	the cell type and value (return value)

Returns: FREEXL_OK will be returned on success

Examples: xl2sql.c.

◆ freexl_get_FAT_entry()

FREEXL_DECLARE int freexl_get_FAT_entry	(	const void *	xls_handle,
		unsigned int	sector_index,
		unsigned int *	next_sector_index
	)

Retrieve FAT entries from FAT chain.

Parameters

xls_handle	the handle previously returned by freexl_open()
sector_index	the index identifying the Sector entry (base 0).
next_sector_index	the index identifying the next Sector to be accessed in logical order (return value).

Note

The following values imply special meaning:

0xffffffff free / unused sector
0xfffffffe end of chain
0xfffffffd sector used by FAT (map of sectors)
0xfffffffc double-indirect FAT sector (map of FAT sectors)

Returns: FREEXL_OK will be returned on success

Note: This function is not normally required, since FreeXL will handle FAT table entries transparent to the user. It is mainly intended for debugging purposes.

Examples: test_xl.c.

◆ freexl_get_info()

FREEXL_DECLARE int freexl_get_info	(	const void *	xls_handle,
		unsigned short	what,
		unsigned int *	info
	)

Query general information about the Workbook and Worksheets.

Parameters

xls_handle	the handle previously returned by freexl_open()
what	the info to be queried.
info	the corresponding information value (return value)

Note: FREEXL_UNKNOWN will be returned in info if the information is not available, not appropriate or not supported for the file type.

Returns: FREEXL_OK will be returned on success

Valid values for what are:

FREEXL_CFBF_VERSION (returning FREEXL_CFBF_VER_3 or FREEXL_CFBF_VER_4)
FREEXL_CFBF_SECTOR_SIZE (returning FREEXL_CFBF_SECTOR_512 or FREEXL_CFBF_SECTOR_4096)
FREEXL_CFBF_FAT_COUNT (returning the total count of FAT entries in the file)
FREEXL_BIFF_VERSION (return one of FREEXL_BIFF_VER_2, FREEXL_BIFF_VER_3, FREEXL_BIFF_VER_4, FREEXL_BIFF_VER_5, FREEXL_BIFF_VER_8)
FREEXL_BIFF_MAX_RECSIZE (returning FREEXL_BIFF_MAX_RECSZ_2080 or FREEXL_BIFF_MAX_RECSZ_8224)
FREEXL_BIFF_DATEMODE (returning FREEXL_BIFF_DATEMODE_1900 or FREEXL_BIFF_DATEMODE_1904)
FREEXL_BIFF_PASSWORD (returning FREEXL_BIFF_OBFUSCATED or FREEXL_BIFF_PLAIN)
FREEXL_BIFF_CODEPAGE (returning FREEXL_BIFF_ASCII, one of FREEXL_BIFF_CP*,FREEXL_BIFF_UTF16LE or FREEXL_BIFF_MACROMAN)
FREEXL_BIFF_SHEET_COUNT (returning the total number of worksheets)
FREEXL_BIFF_STRING_COUNT (returning the total number of Single String Table entries)
FREEXL_BIFF_FORMAT_COUNT (returning the total number of format entries)
FREEXL_BIFF_XF_COUNT (returning the number of extended format entries)

Examples: test_xl.c, and xl2sql.c.

◆ freexl_get_SST_string()

FREEXL_DECLARE int freexl_get_SST_string	(	const void *	xls_handle,
		unsigned short	string_index,
		const char **	string
	)

Retrieve string entries from SST.

Parameters

xls_handle	the handle previously returned by freexl_open()
string_index	the index identifying the String entry (base 0).
string	the corresponding String value (return value)

Returns: FREEXL_OK will be returned on success

Note: This function is not normally required, since freexl_get_cell_value will return the string where appropriate. It is mainly intended for debugging purposes.

Examples: test_xl.c.

◆ freexl_get_worksheet_name()

FREEXL_DECLARE int freexl_get_worksheet_name	(	const void *	xls_handle,
		unsigned short	sheet_index,
		const char **	string
	)

Query worksheet name.

Parameters

xls_handle	the handle previously returned by freexl_open()
sheet_index	the index identifying the worksheet (base 0)
string	the name of the worksheet (return value)

Returns: FREEXL_OK will be returned on success

Examples: test_xl.c, and xl2sql.c.

◆ freexl_open()

FREEXL_DECLARE int freexl_open	(	const char *	path,
		const void **	xls_handle
	)

Open the .xls file, preparing for future functions.

Parameters

path	full or relative pathname of the input .xls file.
xls_handle	an opaque reference (handle) to be used in each subsequent function (return value).

Returns: FREEXL_OK will be returned on success, otherwise any appropriate error code on failure.

Note: You are expected to freexl_close() even on failure, so as to correctly release any dynamic memory allocation.

Examples: test_xl.c, and xl2sql.c.

◆ freexl_open_info()

FREEXL_DECLARE int freexl_open_info	(	const char *	path,
		const void **	xls_handle
	)

Open the .xls file for metadata query only.

This is similar to freexl_open(), except that an abbreviated parsing step is performed. This makes it faster, but does not support queries for cell values.

Parameters

path	full or relative pathname of the input .xls file.
xls_handle	an opaque reference (handle) to be used in each subsequent function (return value).

Returns: FREEXL_OK will be returned on success, otherwise any appropriate error code on failure.

Note: You are expected to freexl_close() even on failure, so as to correctly release any dynamic memory allocation.

◆ freexl_select_active_worksheet()

FREEXL_DECLARE int freexl_select_active_worksheet	(	const void *	xls_handle,
		unsigned short	sheet_index
	)

Set the currently active worksheets.

Within a FreeXL handle, only one worksheet can be active at a time. Functions that fetch data are implictly working on the selected worksheet.

Parameters

xls_handle	the handle previously returned by freexl_open()
sheet_index	the index identifying the worksheet (base 0)

Returns: FREEXL_OK will be returned on success

Examples: test_xl.c, and xl2sql.c.

◆ freexl_version()

FREEXL_DECLARE const char* freexl_version ( void )

Return the current library version.

Returns: the version string.

◆ freexl_worksheet_dimensions()

FREEXL_DECLARE int freexl_worksheet_dimensions	(	const void *	xls_handle,
		unsigned int *	rows,
		unsigned short *	columns
	)

Query worksheet dimensions.

This function returns the number of rows and columns for the currently selected worksheet.

Parameters

xls_handle	the handle previously returned by freexl_open()
rows	the total row count (return value)
columns	the total column count (return value)

Returns: FREEXL_OK will be returned on success

Note: Worksheet dimensions are zero based, so if you have a worksheet that is four columns and two rows (i.e. from A1 in the top left corner to B4 in the bottom right corner), this will return rows equal to 1 and columns equal to 3). This is to support C style looping.

Examples: test_xl.c, and xl2sql.c.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ FREEXL_BIFF_UNSELECTED_SHEET

◆ FREEXL_CFBF_ILLEGAL_MINI_FAT_ENTRY

◆ FREEXL_CFBF_READ_ERROR

◆ FREEXL_CFBF_SEEK_ERROR

◆ FREEXL_CRAFTED_FILE

◆ FREEXL_ILLEGAL_MULRK_VALUE

◆ FREEXL_ILLEGAL_RK_VALUE

◆ FREEXL_INVALID_MINI_STREAM

◆ FREEXL_UNSUPPORTED_CHARSET

Typedef Documentation

◆ FreeXL_CellValue

Function Documentation

◆ freexl_close()

◆ freexl_get_active_worksheet()

◆ freexl_get_cell_value()

◆ freexl_get_FAT_entry()

◆ freexl_get_info()

◆ freexl_get_SST_string()

◆ freexl_get_worksheet_name()

◆ freexl_open()

◆ freexl_open_info()

◆ freexl_select_active_worksheet()

◆ freexl_version()

◆ freexl_worksheet_dimensions()