All TFORMer functions accepting filenames may also be called with a name of a ZIP-file or with a BASE64 encoded string (which may contain a zip-file again). More...

Functions
HTUNZIPPER	TecUnzipper_Alloc (LPCSTR pszFilename)
	Allocate a new unzipper handle.
HTUNZIPPER	TecUnzipper_AllocW (LPCWSTR pszFilename)
	Allocate a new unzipper handle.
VOID	TecUnzipper_Free (HTUNZIPPER htUnzipper)
	Frees an unzipper-handle allocated by TecUnzipper_Alloc.
ERRCODE	TecUnzipper_DeleteAllFiles (HTUNZIPPER htUnzipper)
	Deletes all files and directories on disk that have been created by TecUnzipper_Extract.
ERRCODE	TecUnzipper_Base64Decode (HTUNZIPPER htUnzipper)
	Tests if the passed to TecUnzipper_Alloc is a BASE64 encoded string and decodes it to a temporary file.
ERRCODE	TecUnzipper_Extract (HTUNZIPPER htUnzipper, LPCSTR pszDirectory)
	Extracts a ZIP file into a temporary directory.
ERRCODE	TecUnzipper_ExtractW (HTUNZIPPER htUnzipper, LPCWSTR pszDirectory)
	Extracts a ZIP file into a temporary directory.
INT	TecUnzipper_GetFileCount (HTUNZIPPER htUnzipper)
	Returns the number of files that have been extracted.
LPCSTR	TecUnzipper_GetFile (HTUNZIPPER htUnzipper, INT nIndex)
	Returns the filename with the specified index (0..TecUnzipper_GetFileCount - 1).
INT	TecUnzipper_FindFileByExt (HTUNZIPPER htUnzipper, LPCSTR pszExtension, INT nStartIndex, BOOL bCaseInsensitiveSearch)
	Finds the first file in the set of extracted files that matches the specified file extension.
INT	TecUnzipper_FindFileByExtW (HTUNZIPPER htUnzipper, LPCWSTR pszExtension, INT nStartIndex, BOOL bCaseInsensitiveSearch)
	Finds the first file in the set of extracted files that matches the specified file-extension.
LPSTR	TecUnzipper_Base64_Encode (LPCSTR szData, LONG lLen)
	Creates a BASE64 encoded string.
VOID	TecUnzipper_Base64_Free (LPSTR szStr)
	Free a BASE64 encoded string created with TecUnzipper_Base64_Encode.
LPCSTR	TecUnzipper_GetFilename (HTUNZIPPER htUnzipper)
	Returns the filename of the zip file being used or of the temp file created by TecUnzipper_Base64Decode.

Detailed Description

All TFORMer functions accepting filenames may also be called with a name of a ZIP-file or with a BASE64 encoded string (which may contain a zip-file again).

Functions in this group enable the software developer to implement an optimized handling of such zip-files (or BASE64 string).

Usually all TFORMer functions accepting files are trying to determine if it is a zip-file automatically (a BASE64 encoded file is determined by the BASE64: prefix). When TFORMer detects a zip-file it is unzipped automatically to the temp-directory of the current user. This automatic unzipping requires TFORMer to clean up such temporary files after the function call ends. If you want to avoid the per-function unzipping and deleting, then implement the unzipping functionality yourself by the TecUnzipper-functions. Thereafter pass the resulting files to the TFORMer functions.

Some declarations

    ERRCODE eCode       = ErrOk;
    LPCSTR  pszFilename = "repository.zip";

Allocate an unzipper handle

      HTUNZIPPER hZip = TecUnzipper_Alloc( pszFilename );
      if( !hZip )
        return ERROR_OUTOFMEMORY;

Make sure that data is always BASE64 decoded. Not required in this case, but should be always done so that you can pass strings starting with "BASE64:" to TecUnzipper_Alloc
```
      TecUnzipper_Base64Decode( hZip );
```

Extract data to a temporary directory

      eCode = TecUnzipper_Extract( hZip, NULL );

Check the return code to see if extracting was successful
```
      if( eCode == ErrOk )
      {
```

Find the first Repository in the zip file

        INT nIndex  = TecUnzipper_FindFileByExt( hZip, "TFR", -1, TRUE );
        if( nIndex == -1 )

The zip archive does not contain a TFORMer Repository file.

          eCode = ERROR_FILE_NOT_FOUND;
        else

Get the absolute path to the extracted Repository file.

          pszFilename = TecUnzipper_GetFile( hZip, nIndex );
      }
      else
      {

The passed filename was neither a zip file nor a base 64 encoded string. Ignore the error and work with the data as a normal TFR file.
```
        pszFilename = TecUnzipper_GetFilename( hZip );
        eCode       = ErrOk;
      }
```
pszFilename contains now the path to a normal temporary TFR file
Do something with pszFilename now ...

Delete created temporary files

    TecUnzipper_DeleteAllFiles( hZip );

Free the unzipper handle
```
      TecUnzipper_Free( hZip );
```

Function Documentation

HTUNZIPPER TecUnzipper_Alloc ( LPCSTR pszFilename )

Allocate a new unzipper handle.

TFORMer functions accepting filenames like TFormer_SetRepositoryName, TFormer_SetDataFileXML, ... are accepting the following parameters:

Plain file names (*.tfr, *.tff, *.xml)
Zipped files (zipped *.tfr, zipped *.tff, ...)
BASE64 encoded strings containing plain or zip files (in such a case the string must start with BASE64:)

Usually all TFORMer functions accepting files are trying to determine if it is a zip-file automatically (a BASE64 encoded file is determined by the BASE64: prefix). When TFORMer detects a zip-file it is unzipped automatically to the temp-directory of the current user. This automatic unzipping requires TFORMer to clean up such temporary files after the function call ends. If you want to avoid the per-function unzipping and deleting, then implement the unzipping functionality yourself by the TecUnzipper-functions.

This function may be changed in the future.

Note:: Free allocated memory with TecUnzipper_Free after use.

Returns:: A valid handle or NULL if the handle could not be allocated

Parameters:

pszFilename The filename of a valid zip file or a BASE64 encoded string (e.g. BASE64:h/5tzWP%$378jdfh...)

HTUNZIPPER TecUnzipper_AllocW ( LPCWSTR pszFilename )

Allocate a new unzipper handle.

TFORMer functions accepting filenames like TFormer_SetRepositoryName, TFormer_SetDataFileXML, ... are accepting the following parameters:

Plain file names (*.tfr, *.tff, *.xml)
Zipped files (zipped *.tfr, zipped *.tff, ...)
BASE64 encoded strings containing plain or zip files (in such a case the string must start with BASE64:)

Usually all TFORMer functions accepting files are trying to determine if it is a zip-file automatically (a BASE64 encoded file is determined by the BASE64: prefix). When TFORMer detects a zip-file it is unzipped automatically to the temp-directory of the current user. This automatic unzipping requires TFORMer to clean up such temporary files after the function call ends. If you want to avoid the per-function unzipping and deleting, then implement the unzipping functionality yourself by the TecUnzipper-functions.

This function may be changed in the future.

Note:: Free allocated memory with TecUnzipper_Free after use.

Returns:: A valid handle or NULL if the handle could not be allocated

Parameters:

pszFilename The filename of a valid zip file or a BASE64 encoded string (e.g. BASE64:h/5tzWP%$378jdfh...)

LPSTR TecUnzipper_Base64_Encode	(	LPCSTR	szData,
		LONG	lLen
	)

Creates a BASE64 encoded string.

This is a helper function for non .NET based environments. When using .NET use the Convert class. This function may be changed in the future.

See also:: TecUnzipper_Base64_Free

Returns:: A zero-terminated buffer containing a BASE64 encoded string. Free this buffer yourself with TecUnzipper_Base64_Free.

Parameters:

szData	A pointer to a binary buffer containing the data to be encoded
lLen	The number of bytes contained in the buffer

VOID TecUnzipper_Base64_Free ( LPSTR szStr )

Free a BASE64 encoded string created with TecUnzipper_Base64_Encode.

This function may be changed in the future

See also:: TecUnzipper_Base64_Encode

Parameters:

szStr A pointer to a BASE64 buffer returned by TecUnzipper_Base64_Encode

ERRCODE TecUnzipper_Base64Decode ( HTUNZIPPER htUnzipper )

Tests if the passed to TecUnzipper_Alloc is a BASE64 encoded string and decodes it to a temporary file.

The string must start with BASE64:. An error is returned otherwise.

See also:: TecUnzipper_Alloc

Returns:: ErrOk(0) on success

Parameters:

htUnzipper TECUnzipper-handle - see TecUnzipper_Alloc

ERRCODE TecUnzipper_DeleteAllFiles ( HTUNZIPPER htUnzipper )

Deletes all files and directories on disk that have been created by TecUnzipper_Extract.

This function may be changed in the future.

Returns:: ErrOk(0) on success

See also:: TecUnzipper_Extract

Parameters:

htUnzipper TECUnzipper-handle - see TecUnzipper_Alloc

ERRCODE TecUnzipper_Extract	(	HTUNZIPPER	htUnzipper,
		LPCSTR	pszDirectory
	)

Extracts a ZIP file into a temporary directory.

This function may be changed in the future.

Returns:: ErrOk(0) on success or an error if the data passed to TecUnzipper_Alloc was not a valid zip-file

Parameters:

htUnzipper	TECUnzipper-handle - see TecUnzipper_Alloc
pszDirectory	Path for the target folder, `NULL` if TFORMer should create a temporary directory

ERRCODE TecUnzipper_ExtractW	(	HTUNZIPPER	htUnzipper,
		LPCWSTR	pszDirectory
	)

Extracts a ZIP file into a temporary directory.

This function may be changed in the future.

Returns:: ErrOk(0) on success or an error if the data passed to TecUnzipper_Alloc was not a valid zip-file

Parameters:

htUnzipper	TECUnzipper-handle - see TecUnzipper_Alloc
pszDirectory	Path for the target folder, `NULL` if TFORMer should create a temporary directory

INT TecUnzipper_FindFileByExt	(	HTUNZIPPER	htUnzipper,
		LPCSTR	pszExtension,
		INT	nStartIndex,
		BOOL	bCaseInsensitiveSearch
	)

Finds the first file in the set of extracted files that matches the specified file extension.

Finds the first file matching the specified file extension contained in an (optional BASE64 encoded) zip file. Usually this function is used to find contained *.tfr or *.tff files. Call this function only if TecUnzipper_Extract returned ErrOk(0).

This function may be changed in the future.

See also:: TecUnzipper_GetFile, TecUnzipper_Extract

Returns:: The index of the first found file or -1 if no file was found (see TecUnzipper_GetFile)

Parameters:

htUnzipper	TECUnzipper-handle - see TecUnzipper_Alloc
pszExtension	Search file with this file extension only (the file extension must be specified without a dot at the beginning - e.g. tff)
nStartIndex	Start index to start the search with (-1 for start at the beginning)
bCaseInsensitiveSearch	`TRUE` if the case should be case insensitive

INT TecUnzipper_FindFileByExtW	(	HTUNZIPPER	htUnzipper,
		LPCWSTR	pszExtension,
		INT	nStartIndex,
		BOOL	bCaseInsensitiveSearch
	)

Finds the first file in the set of extracted files that matches the specified file-extension.

Finds the first file matching the specified file extension contained in an (optional BASE64 encoded) zip file. Usually this function is used to find contained *.tfr or *.tff files. Call this function only if TecUnzipper_Extract returned ErrOk(0).

This function may be changed in the future.

See also:: TecUnzipper_GetFile, TecUnzipper_Extract

Returns:: The index of the first found file or -1 if no file was found (see TecUnzipper_GetFile)

Parameters:

htUnzipper	TECUnzipper-handle - see TecUnzipper_Alloc
pszExtension	Search file with this file extension only (the file extension must be specified without a dot at the beginning - e.g. tff)
nStartIndex	Start index to start the search with (-1 for start at the beginning)
bCaseInsensitiveSearch	`TRUE` if the case should be case insensitive

VOID TecUnzipper_Free ( HTUNZIPPER htUnzipper )

Frees an unzipper-handle allocated by TecUnzipper_Alloc.

Free allocated memory with TecUnzipper_Free after use. Files unzipped with functions of this group are not deleted automatically, call TecUnzipper_DeleteAllFiles to do this.

This function may be changed in the future.

Parameters:

htUnzipper TECUnzipper-handle - see TecUnzipper_Alloc

LPCSTR TecUnzipper_GetFile	(	HTUNZIPPER	htUnzipper,
		INT	nIndex
	)

Returns the filename with the specified index (0..TecUnzipper_GetFileCount - 1).

Returns the absolute filename for the file with the specified index. The index starts at 0 and must be smaller than the return value of TecUnzipper_GetFileCount. This function may be changed in the future.

See also:: TecUnzipper_GetFileCount, TecUnzipper_FindFileByExt

Returns:: The absolute filename or NULL if the index is out of range. The returned string is only temporary available and should be copied immediately!

Parameters:

htUnzipper	TECUnzipper-handle - see TecUnzipper_Alloc
nIndex	0-based file index

INT TecUnzipper_GetFileCount ( HTUNZIPPER htUnzipper )

Returns the number of files that have been extracted.

Returns the number of files that have been extracted with TecUnzipper_Extract. If no zip-file was specified (e.g. simply passing a BASE64 encoded tff) with TecUnzipper_Alloc then the return value is 1. Use TecUnzipper_GetFile for iterating the single files contained in the zip or BASE64 string.

This function may be changed in the future.

See also:: TecUnzipper_GetFile

Returns:: the number of files that have been extracted

Parameters:

htUnzipper TECUnzipper-handle - see TecUnzipper_Alloc

LPCSTR TecUnzipper_GetFilename ( HTUNZIPPER htUnzipper )

Returns the filename of the zip file being used or of the temp file created by TecUnzipper_Base64Decode.

This function may be changed in the future

See also:: TecUnzipper_Base64_Encode

Returns:: A filename or NULL in case of an error. The returned string is only temporary available and should be copied immediately!

Parameters:

htUnzipper TECUnzipper-handle - see TecUnzipper_Alloc

© 2006-2024 - all rights reserved by TEC-IT Datenverarbeitung GmbH
Generated on Sat Oct 5 2024 05:08:16 for TFORMer SDK - DLL/Library with doxygen 1.7.6.1