CkByteData C Reference Documentation

CkByteData

Current Version: 9.5.0.73

Represents a chunk of byte data and provides methods for accessing it, adding to it, or saving and loading from files.

Create/Dispose

HCkByteData instance = CkByteData_Create();
// ...
CkByteData_Dispose(instance);
HCkByteData CkByteData_Create(void);

Creates an instance of the HCkByteData object and returns a handle ("void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.

void CkByteData_Dispose(HCkByteData handle);

Objects created by calling CkByteData_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkByteData_Dispose.

Properties

SecureClear
BOOL CkByteData_getSecureClear(HCkByteData cHandle);
void CkByteData_putSecureClear(HCkByteData cHandle, BOOL newVal);
Introduced in version 9.5.0.73

If set to TRUE, then memory is always first overwritten with zero bytes prior to deallocation. The default value of this property is FALSE.

top

Methods

append
void CkByteData_append(HCkByteData cHandle, HCkByteData db);

Appends byte data to the data already contained in the object.

top
append2
void CkByteData_append2(HCkByteData cHandle, const unsigned char *pByteData, unsigned long szByteData);

Appends bytes to the data already contained in the object.

top
appendChar
void CkByteData_appendChar(HCkByteData cHandle, char ch);

Appends a single byte.

top
appendCharN
void CkByteData_appendCharN(HCkByteData cHandle, char ch, int numTimes);

Appends a single char N times. The equivalent of calling appendChar N times.

top
appendEncoded
void CkByteData_appendEncoded(HCkByteData cHandle, const char *str, const char *encoding);

Appends binary data from an encoded string. The encoding can be specified as "hex", "base64", "url", "quoted-printable", "modBase64", "base58", or "base32". The input string is decoded from the specified encoding and the binary data is appended to the calling object's content.

top
appendEncodedW
void CkByteData_appendEncodedW(HCkByteData cHandle, const wchar_t * str, const wchar_t * encoding);

To be documented soon...

top
appendFile
BOOL CkByteData_appendFile(HCkByteData cHandle, const char *path);

Opens a file for binary read, appends the file contents, and closes the file.

top
appendFileW
BOOL CkByteData_appendFileW(HCkByteData cHandle, const wchar_t * path);

To be documented soon...

top
appendInt
void CkByteData_appendInt(HCkByteData cHandle, int intValue, BOOL littleEndian);

Appends a 32-bit signed integer (4 bytes) to the data already contained in the object. littleEndian determines whether the big endian or little endian byte ordering is used.

top
appendRandom
void CkByteData_appendRandom(HCkByteData cHandle, int numBytes);

Appends numBytes random bytes to the data already contained within the object.

top
appendRange
void CkByteData_appendRange(HCkByteData cHandle, HCkByteData byteData, unsigned long index, unsigned long numBytes);

Appends a range of bytes from byteData to the data contained withing the caller. The first byte is at index 0.

top
appendShort
void CkByteData_appendShort(HCkByteData cHandle, short shortValue, BOOL littleEndian);

Appends a 16-bit signed integer (2 bytes) to the data already contained in the object. littleEndian determines whether the big endian or little endian byte ordering is used.

top
appendStr
void CkByteData_appendStr(HCkByteData cHandle, const char *str);

Appends a null-terminated string to the data, without including the terminating null.

top
appendStrW
void CkByteData_appendStrW(HCkByteData cHandle, const wchar_t * str, const wchar_t * charset);

To be documented soon...

top
beginsWith
BOOL CkByteData_beginsWith(HCkByteData cHandle, HCkByteData byteDataObj);

Returns TRUE if the caller's data begins with the exact bytes contained within byteDataObj.

top
beginsWith2
BOOL CkByteData_beginsWith2(HCkByteData cHandle, const unsigned char *pByteData, unsigned long szByteData);

Returns TRUE if the caller's data begins with specified bytes.

top
borrowData
void CkByteData_borrowData(HCkByteData cHandle, const unsigned char *pByteData, unsigned long szByteData);

Sets the CkByteData's data pointer and size to memory outside the object. This is useful in cases where a CkByteData object is needed, but copying data into the CkByteData is not desired.

Note: The borrowData method can only be used for data that is being passed into a Chilkat method call. It is not for use as a buffer for Chilkat to deposit data. This is not the intent of the method.

More Information and Examples
top
byteSwap4321
void CkByteData_byteSwap4321(HCkByteData cHandle);

4321 byte swaps the data contained within the object.

top
clear
void CkByteData_clear(HCkByteData cHandle);

Clears the CkByteData object of all data.

top
encode
void CkByteData_encode(HCkByteData cHandle, const char *encoding, HCkString str);

Encodes binary data according to the encoding requested. The encoding can be specified as "hex", "base64", "url", "quoted-printable", "modBase64", "base58", "base32", "qp-", "url_rfc1738", "url_rfc2396", or "url_rfc3986".

top
encodeW
void CkByteData_encodeW(HCkByteData cHandle, const wchar_t * encoding, HCkString str);

To be documented soon...

top
ensureBuffer
BOOL CkByteData_ensureBuffer(HCkByteData cHandle, unsigned long expectedNumBytes);

This method can be called to help optimize internal memory re-allocation. If, for example, many calls will be made to append data, and the total size is approximately known, then this method can be called to pre-allocate the internal buffer to the expected total size.

Returns TRUE for success, FALSE for failure.

top
equals
BOOL CkByteData_equals(HCkByteData cHandle, HCkByteData compareBytes);

Returns TRUE if compareBytes contains exactly the same content as the caller. Otherwise returns FALSE.

top
equals2
BOOL CkByteData_equals2(HCkByteData cHandle, const unsigned char *pCompareBytes, unsigned long numBytes);

Returns TRUE if the bytes pointed to by pCompareBytes contains exactly the same content as the caller. Otherwise returns FALSE.

top
findBytes
int CkByteData_findBytes(HCkByteData cHandle, HCkByteData byteDataObj);

Locates the first occurrence of the bytes contained in byteDataObj and returns the index of where these bytes occur in the caller's data. Returns -1 if not found.

top
findBytes2
int CkByteData_findBytes2(HCkByteData cHandle, const unsigned char *findBytes, unsigned long findBytesLen);

Locates the first occurrence of the specified bytes and returns the index of where these bytes occur in the caller's data. Returns -1 if not found.

top
getByte
unsigned char CkByteData_getByte(HCkByteData cHandle, unsigned long byteIndex);

Returns the Nth byte of the binary data. The 1st byte is at index 0.

top
getBytes
const unsigned char *CkByteData_getBytes(HCkByteData cHandle);
This method is deprecated. It will be removed in a future version.

Returns a pointer to the bytes contained within the object. Be very careful with the pointer that is returned. If more data is appended to the object, an internal reallocation may occur such that the previously returned pointer is no longer valid.

This method is identical to the getData method. Use getData instead.

top
getChar
char CkByteData_getChar(HCkByteData cHandle, unsigned long byteIndex);

Returns the Nth byte of the binary content as a "char". The 1st byte is at index 0.

top
getData
const unsigned char *CkByteData_getData(HCkByteData cHandle);

Returns a pointer to the internal buffer. Be careful with this method because if additional data is appended, the data within the object may be relocated and the pointer may cease to be valid.

top
getDataAt
const unsigned char *CkByteData_getDataAt(HCkByteData cHandle, unsigned long byteIndex);

Same as getData, except it gets a pointer to the data at a byte offset. (0 = the start of buffer)

top
getEncodedW
const wchar_t * CkByteData_getEncodedW(HCkByteData cHandle, const wchar_t * encoding);

The utf-16 version of getEncoded.

top
getInt
int CkByteData_getInt(HCkByteData cHandle, unsigned long byteIndex);

Returns the 4-byte integer located at a specific byte index.

top
getRange
const unsigned char *CkByteData_getRange(HCkByteData cHandle, unsigned long byteIndex, unsigned long numBytes);

Copies a range of bytes to a separate internal memory buffer and returns the pointer to the bytes. The returned pointer is only valid while the object exists. Also, any subsequent calls to getRange, getRangeStr, or to_s will invalidate the buffer.

top
getShort
short CkByteData_getShort(HCkByteData cHandle, unsigned long byteIndex);

Returns the 2-byte integer located at a specific byte index.

top
getSize
unsigned long CkByteData_getSize(HCkByteData cHandle);

Returns the number of bytes in the data buffer.

top
getUInt
unsigned long CkByteData_getUInt(HCkByteData cHandle, unsigned long byteIndex);

Returns the 4-byte unsigned integer located at a specific byte index.

top
getUShort
unsigned short CkByteData_getUShort(HCkByteData cHandle, unsigned long byteIndex);

Returns the 2-byte unsigned integer located at a specific byte index.

top
is7bit
BOOL CkByteData_is7bit(HCkByteData cHandle);

Returns TRUE if all the bytes are in the range 0x00 to 0x7F.

top
loadFile
BOOL CkByteData_loadFile(HCkByteData cHandle, const char *path);

Equivalent to clear() followed by appendFile().

top
loadFileW
BOOL CkByteData_loadFileW(HCkByteData cHandle, const wchar_t * path);

To be documented soon...

top
pad
void CkByteData_pad(HCkByteData cHandle, int blockSize, int paddingScheme);

Pads the data to a multiple of the blockSize using a cryptographic padding scheme specified by paddingScheme. The possible integer values for paddingScheme are the same as those listed for the PaddingScheme property of the CkCrypt2 class.

top
preAllocate
BOOL CkByteData_preAllocate(HCkByteData cHandle, unsigned long expectedNumBytes);
This method is deprecated. It will be removed in a future version.

This method can be called to help optimize internal memory re-allocation. If, for example, many calls will be made to append data, and the total size is approximately known, then this method can be called to pre-allocate the internal buffer to the expected total size.

This method is identical to the ensureBuffer method. Use ensureBuffer instead.

top
removeChunk
void CkByteData_removeChunk(HCkByteData cHandle, unsigned long startIndex, unsigned long numBytes);

Removes (discards) a range from the data.

top
removeData
const unsigned char *CkByteData_removeData(HCkByteData cHandle);

Removes the data from the CkByteData object. The caller will receivea pointer to the memory buffer, and is responsible for deleting it.
Example:
unsigned char *data = byteData.removeData();
... do something with the data....
delete [] data;

top
replaceChar
void CkByteData_replaceChar(HCkByteData cHandle, unsigned char existingByteValue, unsigned char replacementByteValue);

Replaces all occurrences of existingByteValue with replacementByteValue.

top
saveFile
BOOL CkByteData_saveFile(HCkByteData cHandle, const char *path);

Saves the byte data to a file. If the file already exists, it will be overwritten.

top
saveFileW
BOOL CkByteData_saveFileW(HCkByteData cHandle, const wchar_t * path);

To be documented soon...

top
shorten
void CkByteData_shorten(HCkByteData cHandle, unsigned long numBytes);

Discards N bytes from the end of the data.

top
to_ws
const wchar_t * CkByteData_to_ws(HCkByteData cHandle, const char *charset);

To be documented soon...

top
unpad
void CkByteData_unpad(HCkByteData cHandle, int blockSize, int paddingScheme);

Unpads the data from a multiple of the blockSize to the original data size using a cryptographic padding scheme specified by paddingScheme. The possible integer values for paddingScheme are the same as those listed for the PaddingScheme property of the CkCrypt2 class.

top