--- product: Chilkat product_version: 11.7.0 language: c language_label: C class: CkByteData license: free deprecated: false reference_html: https://www.chilkatsoft.com/refdoc/c_CkByteDataRef.html --- # Chilkat CkByteData — C — v11.7.0 > Chilkat 11.7.0 · language=c · class=CkByteData > Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0//classes/CkByteData.md`. > Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/guide.md`. ## Purpose Represents a chunk of byte data and provides methods for accessing it, adding to it, or saving and loading from files. ## Object creation, unlocking and error handling **Create/Dispose** ```c 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. Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in C. ## Member index | Member | Kind | Signature | |---|---|---| | `SecureClear` | property, read/write | `BOOL CkByteData_getSecureClear(HCkByteData cHandle); void CkByteData_putSecureClear(HCkByteData cHandle, BOOL newVal);` | | `append2` | method | `void CkByteData_append2(HCkByteData cHandle, const unsigned char *pByteData, unsigned long szByteData);` | | `appendChar` | method | `void CkByteData_appendChar(HCkByteData cHandle, char ch);` | | `appendCharN` | method | `void CkByteData_appendCharN(HCkByteData cHandle, char ch, int numTimes);` | | `appendEncoded` | method | `void CkByteData_appendEncoded(HCkByteData cHandle, const char *str, const char *encoding);` | | `appendEncodedW` | method | `void CkByteData_appendEncodedW(HCkByteData cHandle, const wchar_t * str, const wchar_t * encoding);` | | `appendFile` | method | `BOOL CkByteData_appendFile(HCkByteData cHandle, const char *path);` | | `appendFileW` | method | `BOOL CkByteData_appendFileW(HCkByteData cHandle, const wchar_t * path);` | | `appendInt` | method | `void CkByteData_appendInt(HCkByteData cHandle, int intValue, BOOL littleEndian);` | | `appendRandom` | method | `void CkByteData_appendRandom(HCkByteData cHandle, int numBytes);` | | `appendShort` | method | `void CkByteData_appendShort(HCkByteData cHandle, short shortValue, BOOL littleEndian);` | | `appendStr` | method | `void CkByteData_appendStr(HCkByteData cHandle, const char *str);` | | `appendStrW` | method | `void CkByteData_appendStrW(HCkByteData cHandle, const wchar_t * str, const wchar_t * charset);` | | `beginsWith2` | method | `BOOL CkByteData_beginsWith2(HCkByteData cHandle, const unsigned char *pByteData, unsigned long szByteData);` | | `borrowData` | method | `void CkByteData_borrowData(HCkByteData cHandle, const unsigned char *pByteData, unsigned long szByteData);` | | `byteSwap4321` | method | `void CkByteData_byteSwap4321(HCkByteData cHandle);` | | `clear` | method | `void CkByteData_clear(HCkByteData cHandle);` | | `dropData` | method | `void CkByteData_dropData(HCkByteData cHandle);` | | `encode` | method | `void CkByteData_encode(HCkByteData cHandle, const char *encoding, HCkString str);` | | `encodeW` | method | `void CkByteData_encodeW(HCkByteData cHandle, const wchar_t * encoding, HCkString str);` | | `ensureBuffer` | method | `BOOL CkByteData_ensureBuffer(HCkByteData cHandle, unsigned long expectedNumBytes);` | | `equals2` | method | `BOOL CkByteData_equals2(HCkByteData cHandle, const unsigned char *pCompareBytes, unsigned long numBytes);` | | `findBytes2` | method | `int CkByteData_findBytes2(HCkByteData cHandle, const unsigned char *findBytes, unsigned long findBytesLen);` | | `getByte` | method | `unsigned char CkByteData_getByte(HCkByteData cHandle, unsigned long byteIndex);` | | `getChar` | method | `char CkByteData_getChar(HCkByteData cHandle, unsigned long byteIndex);` | | `getData` | method | `const unsigned char *CkByteData_getData(HCkByteData cHandle);` | | `getDataAt` | method | `const unsigned char *CkByteData_getDataAt(HCkByteData cHandle, unsigned long byteIndex);` | | `getEncoded` | method | `const char *CkByteData_getEncoded(HCkByteData cHandle, const char *encoding);` | | `getEncodedW` | method | `const wchar_t * CkByteData_getEncodedW(HCkByteData cHandle, const wchar_t * encoding);` | | `getInt` | method | `int CkByteData_getInt(HCkByteData cHandle, unsigned long byteIndex);` | | `getRange` | method | `const unsigned char *CkByteData_getRange(HCkByteData cHandle, unsigned long byteIndex, unsigned long numBytes);` | | `getSize` | method | `unsigned long CkByteData_getSize(HCkByteData cHandle);` | | `getUInt` | method | `unsigned long CkByteData_getUInt(HCkByteData cHandle, unsigned long byteIndex);` | | `is7bit` | method | `BOOL CkByteData_is7bit(HCkByteData cHandle);` | | `loadFile` | method | `BOOL CkByteData_loadFile(HCkByteData cHandle, const char *path);` | | `loadFileW` | method | `BOOL CkByteData_loadFileW(HCkByteData cHandle, const wchar_t * path);` | | `pad` | method | `void CkByteData_pad(HCkByteData cHandle, int blockSize, int paddingScheme);` | | `removeChunk` | method | `void CkByteData_removeChunk(HCkByteData cHandle, unsigned long startIndex, unsigned long numBytes);` | | `removeData` | method | `const unsigned char *CkByteData_removeData(HCkByteData cHandle);` | | `replaceChar` | method | `void CkByteData_replaceChar(HCkByteData cHandle, unsigned char existingByteValue, unsigned char replacementByteValue);` | | `saveFile` | method | `BOOL CkByteData_saveFile(HCkByteData cHandle, const char *path);` | | `saveFileW` | method | `BOOL CkByteData_saveFileW(HCkByteData cHandle, const wchar_t * path);` | | `shorten` | method | `void CkByteData_shorten(HCkByteData cHandle, unsigned long numBytes);` | | `to_ws` | method | `const wchar_t * CkByteData_to_ws(HCkByteData cHandle, const char *charset);` | | `unpad` | method | `void CkByteData_unpad(HCkByteData cHandle, int blockSize, int paddingScheme);` | Deprecated members are listed at the end of this file with their replacements; do not use them in new code. ## Properties ### CkByteData.SecureClear `Chilkat 11.7.0 · c · CkByteData · SecureClear · property · read/write · since 9.5.0.73` ```c BOOL CkByteData_getSecureClear(HCkByteData cHandle); void CkByteData_putSecureClear(HCkByteData cHandle, BOOL newVal); ``` If set to `TRUE`, then memory is always first overwritten with zero bytes prior to deallocation. The default value of this property is `FALSE`. ## Methods ### CkByteData.append2 `Chilkat 11.7.0 · c · CkByteData · append2 · method` ```c void CkByteData_append2(HCkByteData cHandle, const unsigned char *pByteData, unsigned long szByteData); ``` Appends bytes to the data already contained in the object. ### CkByteData.appendChar `Chilkat 11.7.0 · c · CkByteData · appendChar · method` ```c void CkByteData_appendChar(HCkByteData cHandle, char ch); ``` Appends a single byte. ### CkByteData.appendCharN `Chilkat 11.7.0 · c · CkByteData · appendCharN · method` ```c void CkByteData_appendCharN(HCkByteData cHandle, char ch, int numTimes); ``` Appends a single char N times. The equivalent of calling appendChar N times. ### CkByteData.appendEncoded `Chilkat 11.7.0 · c · CkByteData · appendEncoded · method` ```c 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. ### CkByteData.appendEncodedW `Chilkat 11.7.0 · c · CkByteData · appendEncodedW · method` ```c void CkByteData_appendEncodedW(HCkByteData cHandle, const wchar_t * str, const wchar_t * encoding); ``` To be documented soon... ### CkByteData.appendFile `Chilkat 11.7.0 · c · CkByteData · appendFile · method` ```c BOOL CkByteData_appendFile(HCkByteData cHandle, const char *path); ``` Opens a file for binary read, appends the file contents, and closes the file. ### CkByteData.appendFileW `Chilkat 11.7.0 · c · CkByteData · appendFileW · method` ```c BOOL CkByteData_appendFileW(HCkByteData cHandle, const wchar_t * path); ``` Opens a file for binary read, appends the file contents, and closes the file. ### CkByteData.appendInt `Chilkat 11.7.0 · c · CkByteData · appendInt · method` ```c 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. ### CkByteData.appendRandom `Chilkat 11.7.0 · c · CkByteData · appendRandom · method` ```c void CkByteData_appendRandom(HCkByteData cHandle, int numBytes); ``` Appends `numBytes` random bytes to the data already contained within the object. ### CkByteData.appendShort `Chilkat 11.7.0 · c · CkByteData · appendShort · method` ```c 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. ### CkByteData.appendStr `Chilkat 11.7.0 · c · CkByteData · appendStr · method` ```c void CkByteData_appendStr(HCkByteData cHandle, const char *str); ``` Appends a null-terminated string to the data, without including the terminating null. ### CkByteData.appendStrW `Chilkat 11.7.0 · c · CkByteData · appendStrW · method` ```c void CkByteData_appendStrW(HCkByteData cHandle, const wchar_t * str, const wchar_t * charset); ``` To be documented soon... ### CkByteData.beginsWith2 `Chilkat 11.7.0 · c · CkByteData · beginsWith2 · method` ```c BOOL CkByteData_beginsWith2(HCkByteData cHandle, const unsigned char *pByteData, unsigned long szByteData); ``` Returns `TRUE` if the caller's data begins with specified bytes. ### CkByteData.borrowData `Chilkat 11.7.0 · c · CkByteData · borrowData · method` ```c 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. ### CkByteData.byteSwap4321 `Chilkat 11.7.0 · c · CkByteData · byteSwap4321 · method` ```c void CkByteData_byteSwap4321(HCkByteData cHandle); ``` 4321 byte swaps the data contained within the object. ### CkByteData.clear `Chilkat 11.7.0 · c · CkByteData · clear · method` ```c void CkByteData_clear(HCkByteData cHandle); ``` Clears the CkByteData object of all data. The internal memory is deallocated. To clear without deallocating, call dropData instead. ### CkByteData.dropData `Chilkat 11.7.0 · c · CkByteData · dropData · method · since 9.5.0.91` ```c void CkByteData_dropData(HCkByteData cHandle); ``` 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. ### CkByteData.encode `Chilkat 11.7.0 · c · CkByteData · encode · method` ```c 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`. ### CkByteData.encodeW `Chilkat 11.7.0 · c · CkByteData · encodeW · method` ```c void CkByteData_encodeW(HCkByteData cHandle, const wchar_t * encoding, HCkString str); ``` To be documented soon... ### CkByteData.ensureBuffer `Chilkat 11.7.0 · c · CkByteData · ensureBuffer · method` ```c 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. 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. ### CkByteData.equals2 `Chilkat 11.7.0 · c · CkByteData · equals2 · method` ```c BOOL CkByteData_equals2(HCkByteData cHandle, const unsigned char *pCompareBytes, unsigned long numBytes); ``` Returns `TRUE` if the contents of this CkByteData object is exactly equal in both size and content to the bytes passed in `pCompareBytes` and the size passed in `numBytes`. Otherwise returns `FALSE`. Note: Call beginsWith2 to test if the 1st N bytes are equal. ### CkByteData.findBytes2 `Chilkat 11.7.0 · c · CkByteData · findBytes2 · method` ```c 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. ### CkByteData.getByte `Chilkat 11.7.0 · c · CkByteData · getByte · method` ```c unsigned char CkByteData_getByte(HCkByteData cHandle, unsigned long byteIndex); ``` Returns the Nth byte of the binary data. The 1st byte is at index 0. ### CkByteData.getChar `Chilkat 11.7.0 · c · CkByteData · getChar · method` ```c 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. ### CkByteData.getData `Chilkat 11.7.0 · c · CkByteData · getData · method` ```c 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. ### CkByteData.getDataAt `Chilkat 11.7.0 · c · CkByteData · getDataAt · method` ```c 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) ### CkByteData.getEncoded `Chilkat 11.7.0 · c · CkByteData · getEncoded · method · since 9.5.0.47` ```c const char *CkByteData_getEncoded(HCkByteData cHandle, const char *encoding); ``` 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`. ### CkByteData.getEncodedW `Chilkat 11.7.0 · c · CkByteData · getEncodedW · method` ```c const wchar_t * CkByteData_getEncodedW(HCkByteData cHandle, const wchar_t * encoding); ``` The utf-16 version of getEncoded. ### CkByteData.getInt `Chilkat 11.7.0 · c · CkByteData · getInt · method` ```c int CkByteData_getInt(HCkByteData cHandle, unsigned long byteIndex); ``` Returns the 4-byte integer located at a specific byte index. ### CkByteData.getRange `Chilkat 11.7.0 · c · CkByteData · getRange · method` ```c 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. ### CkByteData.getSize `Chilkat 11.7.0 · c · CkByteData · getSize · method` ```c unsigned long CkByteData_getSize(HCkByteData cHandle); ``` Returns the number of bytes in the data buffer. ### CkByteData.getUInt `Chilkat 11.7.0 · c · CkByteData · getUInt · method` ```c unsigned long CkByteData_getUInt(HCkByteData cHandle, unsigned long byteIndex); ``` Returns the 4-byte unsigned integer located at a specific byte index. ### CkByteData.is7bit `Chilkat 11.7.0 · c · CkByteData · is7bit · method` ```c BOOL CkByteData_is7bit(HCkByteData cHandle); ``` Returns `TRUE` if all the bytes are in the range 0x00 to 0x7F. ### CkByteData.loadFile `Chilkat 11.7.0 · c · CkByteData · loadFile · method` ```c BOOL CkByteData_loadFile(HCkByteData cHandle, const char *path); ``` Equivalent to clear() followed by appendFile(). ### CkByteData.loadFileW `Chilkat 11.7.0 · c · CkByteData · loadFileW · method` ```c BOOL CkByteData_loadFileW(HCkByteData cHandle, const wchar_t * path); ``` To be documented soon... ### CkByteData.pad `Chilkat 11.7.0 · c · CkByteData · pad · method` ```c 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. ### CkByteData.removeChunk `Chilkat 11.7.0 · c · CkByteData · removeChunk · method` ```c void CkByteData_removeChunk(HCkByteData cHandle, unsigned long startIndex, unsigned long numBytes); ``` Removes (discards) a range from the data. ### CkByteData.removeData `Chilkat 11.7.0 · c · CkByteData · removeData · method` ```c const unsigned char *CkByteData_removeData(HCkByteData cHandle); ``` Removes the data from the CkByteData object. The caller will receive a pointer to the memory buffer, and is responsible for deleting it. Example: unsigned char \*data = byteData.removeData(); ... do something with the data.... delete \[\] data; ### CkByteData.replaceChar `Chilkat 11.7.0 · c · CkByteData · replaceChar · method` ```c void CkByteData_replaceChar(HCkByteData cHandle, unsigned char existingByteValue, unsigned char replacementByteValue); ``` Replaces all occurrences of `existingByteValue` with `replacementByteValue`. ### CkByteData.saveFile `Chilkat 11.7.0 · c · CkByteData · saveFile · method` ```c BOOL CkByteData_saveFile(HCkByteData cHandle, const char *path); ``` Saves the byte data to a file. If the file already exists, it will be overwritten. ### CkByteData.saveFileW `Chilkat 11.7.0 · c · CkByteData · saveFileW · method` ```c BOOL CkByteData_saveFileW(HCkByteData cHandle, const wchar_t * path); ``` To be documented soon... ### CkByteData.shorten `Chilkat 11.7.0 · c · CkByteData · shorten · method` ```c void CkByteData_shorten(HCkByteData cHandle, unsigned long numBytes); ``` Discards N bytes from the end of the data. ### CkByteData.to_ws `Chilkat 11.7.0 · c · CkByteData · to_ws · method` ```c const wchar_t * CkByteData_to_ws(HCkByteData cHandle, const char *charset); ``` To be documented soon... ### CkByteData.unpad `Chilkat 11.7.0 · c · CkByteData · unpad · method` ```c 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. ## Deprecated members — do not use in new code | Member | Kind | Deprecated in | Use instead | |---|---|---|---| | `append` | method | before 11.6.1 | — | | `appendRange` | method | before 11.6.1 | — | | `beginsWith` | method | before 11.6.1 | — | | `equals` | method | before 11.6.1 | — | | `findBytes` | method | before 11.6.1 | — | | `getBytes` | method | before 11.6.1 | — | | `preAllocate` | method | before 11.6.1 | — | ## Related classes [`CkString`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/CkString.md)