************ * Contents * ************ 1.) BL Functions 2.) BL Structures 3.) License **************** * BL Functions * **************** 1.0) Overview BLAPI( HANDLE) BLCreateFile( LPCTSTR lpFileName, DWORD dwDesiredAccess); BLAPI( BOOL) BLCloseHandle( HANDLE hFile); BLAPI( BOOL) BLWriteObject( HANDLE hFile, VBLObjectHeaderBase* pBase); BLAPI( BOOL) BLPeekObject( HANDLE hFile, VBLObjectHeaderBase* pBase); BLAPI( BOOL) BLSkipObject( HANDLE hFile, VBLObjectHeaderBase* pBase); BLAPI( BOOL) BLReadObject( HANDLE hFile, VBLObjectHeaderBase* pBase); /* obsolete - replaced by BLReadObjectSecure */ BLAPI( BOOL) BLReadObjectSecure( HANDLE hFile, VBLObjectHeaderBase* pBase, size_t expectedSize); BLAPI( BOOL) BLFreeObject( HANDLE hFile, VBLObjectHeaderBase* pBase); BLAPI( BOOL) BLSetApplication( HANDLE hFile, BYTE appID, BYTE appMajor, BYTE appMinor, BYTE appBuild); BLAPI( BOOL) BLSetWriteOptions( HANDLE hFile, DWORD dwCompression, DWORD dwReserved); BLAPI( BOOL) BLGetFileStatistics( HANDLE hFile, VBLFileStatistics* pStatistics); BLAPI( BOOL) BLFlushFileBuffers( HANDLE hFile, DWORD dwFlags); 1.1) BLCreateFile BLAPI( HANDLE) BLCreateFile( LPCTSTR lpFileName, DWORD dwDesiredAccess); Parameters: LPCTSTR lpFileName Pointer to a null-terminated string that specifies the name of the file to create or open. DWORD dwDesiredAccess Specifies the type of access to the file. An application can obtain read access or write access. This parameter can be GENERIC_READ or GENERIC_WRITE. Return Values: If the function succeeds, the return value is an open handle to the specified file. If the function fails, the return value is INVALID_HANDLE_VALUE. Remarks: Use this function to open a BL file with the desired access. 1.2) BLCloseHandle BLAPI( BOOL) BLCloseHandle( HANDLE hFile); Parameters: HANDLE hFile The file handle returned by BLCreateFile. Return Values: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Remarks: Use this function to close a BL file opened with BLCreateFile. 1.3) BLWriteObject BLAPI( BOOL) BLWriteObject( HANDLE hFile, VBLObjectHeaderBase* pBase); Parameters: HANDLE hFile The file handle returned by BLCreateFile. The file handle must have been created with GENERIC_WRITE access to the file. VBLObjectHeaderBase* pBase Pointer to a BL object structure containing the data to be written to the file. Return Values: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Remarks: Use this function to write a BL object to the file. 1.4) BLPeekObject BLAPI( BOOL) BLPeekObject( HANDLE hFile, VBLObjectHeaderBase* pBase); Parameters: HANDLE hFile The file handle returned by BLCreateFile. The file handle must have been created with GENERIC_READ access to the file. VBLObjectHeaderBase* pBase Pointer to a BL object structure that receives the object header description. Return Values: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Remarks: Use this function to read the base header part of a BL object. 1.5) BLSkipObject BLAPI( BOOL) BLSkipObject( HANDLE hFile, VBLObjectHeaderBase* pBase); Parameters: HANDLE hFile The file handle returned by BLCreateFile. The file handle must have been created with GENERIC_READ access to the file. VBLObjectHeaderBase* pBase Pointer to a BL object structure that describes the object to be skipped. Return Values: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Remarks: Use this function to skip a BL object. 1.6) BLReadObject /* obsolete - replaced by BLReadObjectSecure */ BLAPI( BOOL) BLReadObject( HANDLE hFile, VBLObjectHeaderBase* pBase); Parameters: HANDLE hFile The file handle returned by BLCreateFile. The file handle must have been created with GENERIC_READ access to the file. VBLObjectHeaderBase* pBase Pointer to a BL object structure that describes the object to be read. Return Values: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Remarks: Use this function to read a BL object. 1.7) BLReadObjectSecure BLAPI( BOOL) BLReadObjectSecure( HANDLE hFile, VBLObjectHeaderBase* pBase, size_t expectedSize); Parameters: HANDLE hFile The file handle returned by BLCreateFile. The file handle must have been created with GENERIC_READ access to the file. VBLObjectHeaderBase* pBase Pointer to a BL object structure that describes the object to be read. size_t expectedSize Size of BL object structure which is provided by pointer pBase. Return Values: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Remarks: Use this function to read a BL object. 1.8) BLFreeObject BLAPI( BOOL) BLFreeObject( HANDLE hFile, VBLObjectHeaderBase* pBase); Parameters: HANDLE hFile The file handle returned by BLCreateFile. The file handle must have been created with GENERIC_READ access to the file. VBLObjectHeaderBase* pBase Pointer to a BL object structure that describes the object to be freed. Return Values: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Remarks: Use this function to free the memory which has been allocated for a previously read BL object. Altough this is only required for dynamic sized objects such as environment variables it doesn't harm to call this method for fixed sized objects like CAN messages as well. 1.9) BLSetApplication BLAPI( BOOL) BLSetApplication( HANDLE hFile, BYTE appID, BYTE appMajor, BYTE appMinor, BYTE appBuild); Parameters: HANDLE hFile The file handle returned by BLCreateFile. The file handle must have been created with GENERIC_WRITE access to the file. BYTE appID The application identifier. BYTE appMajor The application major version number. BYTE appMinor The application minor version number. BYTE appBuild The application build version number. Return Values: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Remarks: Use this function to specify the application which writes the file. 1.10) BLSetWriteOptions BLAPI( BOOL) BLSetWriteOptions( HANDLE hFile, DWORD dwCompression, DWORD dwReserved); Parameters: HANDLE hFile The file handle returned by BLCreateFile. The file handle must have been created with GENERIC_WRITE access to the file. DWORD dwCompression The compression to be used during write. Valid values range from 0 (no compression) to 9 (maximum compression). DWORD dwReserved Reserved. Must be zero. Return Values: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Remarks: Use this function to set the compression. 1.11) BLGetFileStatistics BLAPI( BOOL) BLGetFileStatistics( HANDLE hFile, VBLFileStatistics* pStatistics); Parameters: HANDLE hFile The file handle returned by BLCreateFile. The file handle must have been created with GENERIC_READ access to the file. VBLFileStatistics* pStatistics The pointer to the file statistics structure. Return Values: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Remarks: Use this function to retrieve the file statistics. 1.12) BLFlushFileBuffers BLAPI( BOOL) BLFlushFileBuffers( HANDLE hFile, DWORD dwFlags); Parameters: HANDLE hFile The file handle returned by BLCreateFile. The file handle must have been created with GENERIC_WRITE access to the file. DWORD dwFlags Flag indicating how to flush. Valid values are: BL_FLUSH_STREAM - flushes all internal streams BL_FLUSH_FILE - flushes the file and combinations thereof. Return Values: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. Remarks: none. ***************** * BL Structures * ***************** 2.0) Overview VBLObjectHeaderBase VBLFileStatistics 2.1) VBLObjectHeaderBase typedef struct VBLObjectHeaderBase_t { DWORD mSignature; /* signature (BL_OBJ_SIGNATURE) */ WORD mHeaderSize; /* sizeof object header */ WORD mHeaderVersion; /* header version (1) */ DWORD mObjectSize; /* object size */ DWORD mObjectType; /* object type (BL_OBJ_TYPE_XXX) */ } VBLObjectHeaderBase; 2.2) VBLFileStatistics typedef struct VBLFileStatistics_t { DWORD mStatisticsSize; /* sizeof (VBLFileStatistics) */ BYTE mApplicationID; /* application ID */ BYTE mApplicationMajor; /* application major number */ BYTE mApplicationMinor; /* application minor number */ BYTE mApplicationBuild; /* application build number */ ULONGLONG mFileSize; /* file size in bytes */ ULONGLONG mUncompressedFileSize; /* uncompressed file size in bytes */ DWORD mObjectCount; /* number of objects */ DWORD mObjectsRead; /* number of objects read */ } VBLFileStatistics; *********** * License * *********** 3.0 Acknowledgement The compression routines used in the BL library derive from the zlib library. 3.1 The zlib Software License zlib (http://www.gzip.org/zlib/) Copyright (C) 1995-2002 Jean-loup Gailly and Mark Adler This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions: · The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required. · Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. · This notice may not be removed or altered from any source distribution. Jean-loup Gailly (jloup@gzip.org) Mark Adler (madler@alumni.caltech.edu) The data format used by the zlib library is described by RFCs (Request for Comments) 1950 to 1952 in the files ftp://ds.internic.net/rfc/rfc1950.txt (zlib format), rfc1951.txt (deflate format) and rfc1952.txt (gzip format).