CkByteData Delphi DLL Reference Documentation

CkByteData

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

Create/Dispose

function CkByteData_Create: HCkByteData; stdcall;

Creates an instance of the HCkByteData object and returns a handle (i.e. a Pointer). The handle is passed in the 1st argument for the functions listed on this page.

procedure CkByteData_Dispose(handle: HCkByteData); stdcall;

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.

Properties

None

Methods

procedure CkByteData_append(objHandle: HCkByteData;
    db: HCkByteData); stdcall;

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

procedure CkByteData_append2(objHandle: HCkByteData;
    pByteData: pbyte;
    szByteData: LongWord); stdcall;

Appends bytes to the data already contained in the object.

procedure CkByteData_appendChar(objHandle: HCkByteData;
    ch: Char); stdcall;

Appends a single byte.

procedure CkByteData_appendCharN(objHandle: HCkByteData;
    ch: Char;
    numTimes: Integer); stdcall;

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

procedure CkByteData_appendEncoded(objHandle: HCkByteData;
    str: pbyte;
    encoding: pbyte); stdcall;

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.

procedure CkByteData_appendEncodedW(objHandle: HCkByteData;
    str: PWideChar;
    encoding: PWideChar); stdcall;

To be documented soon...

function CkByteData_appendFile(objHandle: HCkByteData;
    path: pbyte): wordbool; stdcall;

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

function CkByteData_appendFileW(objHandle: HCkByteData;
    path: PWideChar): wordbool; stdcall;

To be documented soon...

procedure CkByteData_appendInt(objHandle: HCkByteData;
    intValue: Integer;
    littleEndian: wordbool); stdcall;

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.

procedure CkByteData_appendRandom(objHandle: HCkByteData;
    numBytes: Integer); stdcall;

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

procedure CkByteData_appendRange(objHandle: HCkByteData;
    byteData: HCkByteData;
    index: LongWord;
    numBytes: LongWord); stdcall;

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

procedure CkByteData_appendShort(objHandle: HCkByteData;
    shortValue: SmallInt;
    littleEndian: wordbool); stdcall;

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.

procedure CkByteData_appendStr(objHandle: HCkByteData;
    str: pbyte); stdcall;

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

procedure CkByteData_appendStrW(objHandle: HCkByteData;
    str: PWideChar;
    charset: PWideChar); stdcall;

To be documented soon...

function CkByteData_beginsWith(objHandle: HCkByteData;
    byteDataObj: HCkByteData): wordbool; stdcall;

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

function CkByteData_beginsWith2(objHandle: HCkByteData;
    pByteData: pbyte;
    szByteData: LongWord): wordbool; stdcall;

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

procedure CkByteData_borrowData(objHandle: HCkByteData;
    pByteData: pbyte;
    szByteData: LongWord); stdcall;

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 detailed explanation of borrowData

procedure CkByteData_byteSwap4321(objHandle: HCkByteData); stdcall;

4321 byte swaps the data contained within the object.

procedure CkByteData_clear(objHandle: HCkByteData); stdcall;

Clears the CkByteData object of all data.

procedure CkByteData_encode(objHandle: HCkByteData;
    encoding: pbyte;
    str: HCkString); stdcall;

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".

procedure CkByteData_encodeW(objHandle: HCkByteData;
    encoding: PWideChar;
    str: HCkString); stdcall;

To be documented soon...

function CkByteData_ensureBuffer(objHandle: HCkByteData;
    expectedNumBytes: LongWord): wordbool; stdcall;

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.

function CkByteData_equals(objHandle: HCkByteData;
    compareBytes: HCkByteData): wordbool; stdcall;

Returns True if compareBytes contains exactly the same content as the caller. Otherwise returns False.

function CkByteData_equals2(objHandle: HCkByteData;
    pCompareBytes: pbyte;
    numBytes: LongWord): wordbool; stdcall;

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

function CkByteData_findBytes(objHandle: HCkByteData;
    byteDataObj: HCkByteData): Integer; stdcall;

Locates the first occurance 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.

function CkByteData_findBytes2(objHandle: HCkByteData;
    findBytes: pbyte;
    findBytesLen: LongWord): Integer; stdcall;

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

function CkByteData_getByte(objHandle: HCkByteData;
    byteIndex: LongWord): Byte; stdcall;

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

function CkByteData_getBytes(objHandle: HCkByteData): pbyte; stdcall;

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.

function CkByteData_getChar(objHandle: HCkByteData;
    byteIndex: LongWord): Char; stdcall;

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

function CkByteData_getData(objHandle: HCkByteData): pbyte; stdcall;

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.

function CkByteData_getDataAt(objHandle: HCkByteData;
    byteIndex: LongWord): pbyte; stdcall;

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

function CkByteData_getEncoded(objHandle: HCkByteData;
    encoding: pbyte;
    outStr: HCkString): wordbool; stdcall;

function CkByteData_getEncoded(objHandle: HCkByteData;
    encoding: pbyte): pbyte; stdcall;

Introduced in version 9.5.0.47

Returns the binary data as an encoded string. The encoding may be "base64", "hex", "quoted-printable" (or "qp"), "url", "asc", "url_rfc1738", "url_rfc2396", "url_rfc3986", or "url_oauth".

Returns True for success, False for failure.

function CkByteData_getEncodedW(objHandle: HCkByteData;
    encoding: PWideChar): PWideChar; stdcall;

The utf-16 version of getEncoded.

function CkByteData_getInt(objHandle: HCkByteData;
    byteIndex: LongWord): Integer; stdcall;

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

function CkByteData_getRange(objHandle: HCkByteData;
    byteIndex: LongWord;
    numBytes: LongWord): pbyte; stdcall;

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.

function CkByteData_getShort(objHandle: HCkByteData;
    byteIndex: LongWord): SmallInt; stdcall;

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

function CkByteData_getSize(objHandle: HCkByteData): LongWord; stdcall;

Returns the number of bytes in the data buffer.

function CkByteData_getUInt(objHandle: HCkByteData;
    byteIndex: LongWord): LongWord; stdcall;

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

function CkByteData_getUShort(objHandle: HCkByteData;
    byteIndex: LongWord): Word; stdcall;

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

function CkByteData_is7bit(objHandle: HCkByteData): wordbool; stdcall;

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

function CkByteData_loadFile(objHandle: HCkByteData;
    path: pbyte): wordbool; stdcall;

Equivalent to clear() followed by appendFile().

function CkByteData_loadFileW(objHandle: HCkByteData;
    path: PWideChar): wordbool; stdcall;

To be documented soon...

procedure CkByteData_pad(objHandle: HCkByteData;
    blockSize: Integer;
    paddingScheme: Integer); stdcall;

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.

function CkByteData_preAllocate(objHandle: HCkByteData;
    expectedNumBytes: LongWord): wordbool; stdcall;

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.

procedure CkByteData_removeChunk(objHandle: HCkByteData;
    startIndex: LongWord;
    numBytes: LongWord); stdcall;

Removes (discards) a range from the data.

function CkByteData_removeData(objHandle: HCkByteData): pbyte; stdcall;

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;

procedure CkByteData_replaceChar(objHandle: HCkByteData;
    existingByteValue: Byte;
    replacementByteValue: Byte); stdcall;

Replaces all occurances of existingByteValue with replacementByteValue.

function CkByteData_saveFile(objHandle: HCkByteData;
    path: pbyte): wordbool; stdcall;

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

function CkByteData_saveFileW(objHandle: HCkByteData;
    path: PWideChar): wordbool; stdcall;

To be documented soon...

procedure CkByteData_shorten(objHandle: HCkByteData;
    numBytes: LongWord); stdcall;

Discards N bytes from the end of the data.

function CkByteData_to_ws(objHandle: HCkByteData;
    charset: pbyte): PWideChar; stdcall;

To be documented soon...

procedure CkByteData_unpad(objHandle: HCkByteData;
    blockSize: Integer;
    paddingScheme: Integer); stdcall;

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.