OCData

group OCData

Binary data buffer types and utilities.

Enums

enum OCBase64EncodingOptions

Bitmask options to control the format of Base64-encoded output.

These options allow callers to control line breaking and end-of-line characters in Base64-encoded strings. Options may be combined using the bitwise OR operator. Only one line length and one line ending option should be specified.

Values:

enumerator OCBase64EncodingOptionsNone

No line breaks; a single continuous Base64 string.

enumerator OCBase64Encoding64CharacterLineLength

Insert line breaks every 64 characters.

enumerator OCBase64Encoding76CharacterLineLength

Insert line breaks every 76 characters.

enumerator OCBase64EncodingEndLineWithCarriageReturn

Use a carriage return (\r) for line endings.

enumerator OCBase64EncodingEndLineWithLineFeed

Use a line feed (\n) for line endings.

enumerator OCBase64EncodingEndLineWithCarriageReturnLineFeed

Use CRLF (\r\n) line endings.

Functions

OCTypeID OCDataGetTypeID(void)

Returns the unique type identifier for OCData objects.

Returns:

OCTypeID for OCData.

OCDataRef OCDataCreate(const uint8_t *bytes, unsigned long length)

Creates a new immutable data object by copying bytes.

Parameters:

  • bytes – Pointer to the source byte buffer.

  • length – Number of bytes to copy.

Returns:

New OCDataRef, or NULL on failure.

OCDataRef OCDataCreateWithBytesNoCopy(const uint8_t *bytes, unsigned long length)

Creates an immutable data object referencing existing memory (no copy).

Warning

Caller must ensure that bytes remains valid and unmodified.

Parameters:

  • bytes – Pointer to the byte buffer.

  • length – Length of the byte buffer.

Returns:

New OCDataRef, or NULL on failure.

OCDataRef OCDataCreateCopy(OCDataRef theData)

Creates a new OCDataRef by copying an existing one.

Parameters:

  • theData – Source OCDataRef to copy.

Returns:

Copy of the data, or NULL on failure.

OCMutableDataRef OCDataCreateMutable(unsigned long capacity)

Creates a new mutable data object with a specified capacity.

Parameters:

  • capacity – Initial capacity in bytes.

Returns:

New OCMutableDataRef, or NULL on failure.

OCMutableDataRef OCDataCreateMutableCopy(unsigned long capacity, OCDataRef theData)

Creates a mutable copy of existing data with a specified capacity.

Parameters:

  • capacity – Minimum capacity of the new object.

  • theData – Source data to copy (can be NULL).

Returns:

New OCMutableDataRef.

OCDataRef OCDataCreateWithContentsOfFile(const char *path, OCStringRef *errorString)

Reads an entire file into a new OCDataRef.

Attempts to open and read the file at the given path, returning its raw bytes. If the operation fails (e.g. file not found or read error), returns NULL and, if errorString is non-NULL, sets *errorString to a newly created OCStringRef describing the failure (ownership transferred to caller). Pass NULL to ignore error details.

OCStringRef errMsg = NULL;
OCDataRef blob = OCDataCreateWithContentsOfFile("data/sample.jdx", &errMsg);
if (!blob) {
    // handle errMsg...
    OCRelease(errMsg);
} else {
    // use blob...
    OCRelease(blob);
}

Parameters:

  • path – Filesystem path to read.

  • errorString – Optional pointer to an OCStringRef; on failure, *errorString will be set to an explanatory message (ownership transferred to caller). Pass NULL to skip error reporting.

Returns:

An OCDataRef containing the file’s contents on success (ownership transferred to caller), or NULL on failure.

unsigned long OCDataGetLength(OCDataRef data)

Gets the length of a data object.

Parameters:

  • data – OCDataRef or OCMutableDataRef.

Returns:

Length in bytes.

const uint8_t *OCDataGetBytesPtr(OCDataRef data)

Returns a read-only pointer to internal bytes.

Parameters:

  • data – OCDataRef or OCMutableDataRef.

Returns:

Pointer to bytes, or NULL.

uint8_t *OCDataGetMutableBytes(OCMutableDataRef data)

Returns a mutable pointer to internal bytes.

Warning

Use with care. Modifications may affect internal state.

Parameters:

  • data – Mutable data object.

Returns:

Pointer to bytes, or NULL.

bool OCDataGetBytes(OCDataRef data, OCRange range, uint8_t *buffer)

Copies a range of bytes from an OCData object into a buffer.

Parameters:

  • data – The source OCData object.

  • range – The byte range to copy.

  • buffer – Destination buffer (must be large enough).

Returns:

true if the copy succeeded; false if inputs are invalid or out of bounds.

bool OCDataSetLength(OCMutableDataRef data, unsigned long newLength)

Sets the length of a mutable data object.

If the new length is greater than the current length, the extra memory is zero-initialized. If the new length exceeds the current capacity, the buffer is reallocated.

Parameters:

  • data – Mutable data object to resize.

  • newLength – The desired new length in bytes.

Returns:

true if the operation succeeded; false if allocation failed or input was NULL.

bool OCDataIncreaseLength(OCMutableDataRef data, unsigned long extraLength)

Increases the length of a mutable data object by a given amount.

Parameters:

  • data – The mutable data object.

  • extraLength – The number of bytes to add.

Returns:

true if the resize was successful; false on failure or invalid input.

bool OCDataAppendBytes(OCMutableDataRef data, const uint8_t *bytes, unsigned long length)

Appends bytes to the end of a mutable data object.

Grows the data buffer as needed. If allocation fails, no changes are made.

Parameters:

  • data – The mutable data object.

  • bytes – The bytes to append.

  • length – The number of bytes to append.

Returns:

true if the bytes were appended successfully; false on failure.

OCStringRef OCDataCopyFormattingDesc(OCTypeRef cf)

Returns a human-readable string description of a data object.

Parameters:

  • cf – the OCTypeRef instance.

Returns:

A formatted OCStringRef (caller must release).

OCStringRef OCDataCreateBase64EncodedString(OCDataRef data, OCBase64EncodingOptions options)

Encodes an OCDataRef into a Base64-encoded OCStringRef.

Parameters:

  • data – The input OCDataRef containing binary data to encode. Must not be NULL.

  • options – Bitmask of OCBase64EncodingOptions to control line length and line endings.

Returns:

A new OCStringRef containing the Base64-encoded output. Returns NULL on failure. The caller owns the returned string and is responsible for releasing it.

OCDataRef OCDataCreateFromBase64EncodedString(OCStringRef base64String)

Decodes a Base64-encoded OCStringRef into an OCDataRef.

Parameters:

  • base64String – An OCStringRef containing Base64-encoded content. Must not be NULL. Whitespace and line breaks are ignored during decoding.

Returns:

A new OCDataRef containing the decoded binary data, or NULL on failure. The caller owns the returned data object and must release it.

cJSON *OCDataCopyAsJSON(OCDataRef data, bool typed, OCStringRef *outError)

Creates a JSON representation from OCData by Base64-encoding its contents.

This function serializes raw binary data into JSON format. When typed=false, it returns a simple Base64-encoded string. When typed=true, it returns a structured JSON object with “type”: “OCData”, “encoding”: “base64”, and “value”: “<base64-encoded-data>” fields.

Parameters:

  • data – An OCDataRef to serialize. Must not be NULL.

  • typed – If false, returns Base64 string; if true, returns typed object.

  • outError – Optional pointer to receive an error string on failure.

Returns:

A new cJSON string or object containing Base64-encoded data, or cJSON null if serialization fails. Caller is responsible for managing the returned cJSON object.

OCDataRef OCDataCreateFromJSON(cJSON *json, OCStringRef *outError)

Creates an OCDataRef from a Base64-encoded JSON string.

This function expects a cJSON string node containing a Base64-encoded binary payload.

Parameters:

  • json – A cJSON string node.

  • outError – Optional pointer to receive error information if deserialization fails.

Returns:

A new OCDataRef on success, or NULL on failure. Caller is responsible for releasing the returned OCDataRef.

OCJSONEncoding OCDataCopyEncoding(OCDataRef data)

Returns a copy of the JSON encoding preference for an OCData.

OCData must always be encoded when serialized to JSON since JSON has no native binary type. The encoding determines the specific method used:

  • OCJSONEncodingBase64: Base64-encoded string representation (standard)

  • NULL: Use default encoding behavior (typically base64)

Note: OCJSONEncodingNone is not applicable to OCData since JSON cannot represent raw binary.

Parameters:

  • data – The OCDataRef instance.

Returns:

The encoding value.

void OCDataSetEncoding(OCMutableDataRef data, OCJSONEncoding encoding)

Sets the JSON encoding preference for a mutable OCData.

OCData requires encoding for JSON serialization since JSON has no binary type. Supported encodings:

  • OCJSONEncodingBase64: Serialize as base64-encoded string (recommended)

Note: OCJSONEncodingNone is not valid for OCData.

Parameters:

  • data – The OCMutableDataRef instance.

  • encoding – The encoding value to set.