CkByteData Delphi DLL Reference Documentation
CkByteData
Current Version: 10.0.0
Represents a chunk of byte data and provides methods for accessing it, adding to it, or saving and loading from files.
Create/Dispose
var myObject: HCkByteData; begin myObject := CkByteData_Create(); // ... CkByteData_Dispose(myObject); end;
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.
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
SecureClear
procedure CkByteData_putSecureClear(objHandle: HCkByteData; newPropVal: wordbool); stdcall;
If set to True, then memory is always first overwritten with zero bytes prior to deallocation. The default value of this property is False.
topMethods
append
db: HCkByteData) stdcall;
Appends byte data to the data already contained in the object.
topappend2
pByteData: pbyte;
szByteData: LongWord) stdcall;
Appends bytes to the data already contained in the object.
topappendChar
ch: Char) stdcall;
Appends a single byte.
topappendCharN
ch: Char;
numTimes: Integer) stdcall;
Appends a single char N times. The equivalent of calling appendChar N times.
topappendEncoded
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.
topappendEncodedW
str: PWideChar;
encoding: PWideChar) stdcall;
To be documented soon...
topappendFile
path: pbyte): wordbool; stdcall;
Opens a file for binary read, appends the file contents, and closes the file.
topappendFileW
path: PWideChar): wordbool; stdcall;
Opens a file for binary read, appends the file contents, and closes the file.
topappendInt
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.
topappendRandom
numBytes: Integer) stdcall;
Appends numBytes random bytes to the data already contained within the object.
topappendRange
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.
topappendShort
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.
topappendStr
str: pbyte) stdcall;
Appends a null-terminated string to the data, without including the terminating null.
topappendStrW
str: PWideChar;
charset: PWideChar) stdcall;
To be documented soon...
topbeginsWith
byteDataObj: HCkByteData): wordbool; stdcall;
Returns True if the caller's data begins with the exact bytes contained within byteDataObj.
topbeginsWith2
pByteData: pbyte;
szByteData: LongWord): wordbool; stdcall;
Returns True if the caller's data begins with specified bytes.
topborrowData
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.
byteSwap4321
4321 byte swaps the data contained within the object.
topclear
Clears the CkByteData object of all data. The internal memory is deallocated. To clear without deallocating, call dropData instead.
topdropData
Sets the size of the data to 0. Does not deallocate the existing internal buffer. (This is a fast way of "clearing" the CkByteData object, such that the existing data remains in memory and is overwritten on the next append.)
If the SecureClear property is set to True, then the internal memory buffer is zeroed out before resetting the size to 0.
topencode
Encodes binary data according to the encoding requested. The encoding can be specified as "hex", "base64", "url", "quoted-printable", "modBase64", "base58", "base32", "qp-
encodeW
To be documented soon...
topensureBuffer
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.
If the internal buffer is already larger than the expectedNumBytes then nothing happens. The existing internal buffer is kept.
Returns True for success, False for failure.
topequals
compareBytes: HCkByteData): wordbool; stdcall;
Returns True if compareBytes contains exactly the same content as the caller. Otherwise returns False.
topequals2
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.
topfindBytes
byteDataObj: HCkByteData): Integer; stdcall;
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.
topfindBytes2
findBytes: pbyte;
findBytesLen: LongWord): Integer; stdcall;
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.
topgetByte
byteIndex: LongWord): Byte; stdcall;
Returns the Nth byte of the binary data. The 1st byte is at index 0.
topgetChar
byteIndex: LongWord): Char; stdcall;
Returns the Nth byte of the binary content as a "char". The 1st byte is at index 0.
topgetData
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.
topgetDataAt
byteIndex: LongWord): pbyte; stdcall;
Same as getData, except it gets a pointer to the data at a byte offset. (0 = the start of buffer)
topgetEncoded
encoding: pbyte): pbyte; stdcall;
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".
topgetEncodedW
encoding: PWideChar): PWideChar; stdcall;
The utf-16 version of getEncoded.
topgetInt
byteIndex: LongWord): Integer; stdcall;
Returns the 4-byte integer located at a specific byte index.
topgetRange
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.
topgetShort
byteIndex: LongWord): SmallInt; stdcall;
Returns the 2-byte integer located at a specific byte index.
topgetSize
Returns the number of bytes in the data buffer.
topgetUInt
byteIndex: LongWord): LongWord; stdcall;
Returns the 4-byte unsigned integer located at a specific byte index.
topgetUShort
byteIndex: LongWord): Word; stdcall;
Returns the 2-byte unsigned integer located at a specific byte index.
topis7bit
Returns True if all the bytes are in the range 0x00 to 0x7F.
toploadFile
path: pbyte): wordbool; stdcall;
Equivalent to clear() followed by appendFile().
toploadFileW
path: PWideChar): wordbool; stdcall;
To be documented soon...
toppad
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.
topremoveChunk
startIndex: LongWord;
numBytes: LongWord) stdcall;
Removes (discards) a range from the data.
topremoveData
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;
replaceChar
existingByteValue: Byte;
replacementByteValue: Byte) stdcall;
Replaces all occurrences of existingByteValue with replacementByteValue.
topsaveFile
path: pbyte): wordbool; stdcall;
Saves the byte data to a file. If the file already exists, it will be overwritten.
topsaveFileW
path: PWideChar): wordbool; stdcall;
To be documented soon...
topshorten
numBytes: LongWord) stdcall;
Discards N bytes from the end of the data.
topto_ws
charset: pbyte): PWideChar; stdcall;
To be documented soon...
topunpad
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.
top