ArbData objects

ArbData objects are used to communicate custom data between plugins. They are managed through the dqcs_arb_* functions. They are created using dqcs_arb_new():

dqcs_arb_new()

Creates a new ArbData object.

dqcs_handle_t dqcs_arb_new(void)

Returns the handle of the newly created ArbData. The ArbData is initialized with JSON object {} and an empty binary argument list.

ArbData objects support the handle and arb APIs.

Unlike most other objects, the data contained within one ArbData object can also be copied to another ArbData.

dqcs_arb_assign()

Copies the data from one object to another.

dqcs_return_t dqcs_arb_assign(
    dqcs_handle_t dest,
    dqcs_handle_t src
)

JSON-like data

To prevent the API from exploding, DQCsim does not provide any functions to manipulate the JSON data; you can only read and write the complete object in one go.

dqcs_arb_json_get()

Returns the JSON/CBOR object of an ArbData object in the form of a JSON string.

char *dqcs_arb_json_get(dqcs_handle_t arb)

On success, this returns a newly allocated string containing the JSON string. Free it with free() when you're done with it to avoid memory leaks. On failure, this returns NULL.

dqcs_arb_json_set()

Sets the JSON/CBOR object of an ArbData object by means of a JSON string.

dqcs_return_t dqcs_arb_json_set(
    dqcs_handle_t arb,
    const char *json
)

You can also read and write the object using CBOR. This is potentially much faster, because it's a binary format.

dqcs_arb_cbor_get()

Returns the JSON/CBOR object of an ArbData object in the form of a CBOR object.

ssize_t dqcs_arb_cbor_get(
    dqcs_handle_t arb,
    void *obj,
    size_t obj_size
)

If the actual size of the object differs from the specified object size, this function will copy the minimum of the actual and specified sizes number of bytes, and return what the actual size was.

If the specified object size is zero, obj is allowed to be NULL. You can use this to query the size before allocating an object.

This function returns -1 on failure.

dqcs_arb_cbor_set()

Sets the JSON/CBOR object of an ArbData object by means of a CBOR object.

dqcs_return_t dqcs_arb_cbor_set(
    dqcs_handle_t arb,
    const void *obj,
    size_t obj_size
)

Binary strings

Unlike the JSON object, the binary string list (a.k.a. unstructured data) is managed by DQCsim. Therefore, DQCsim provides all the list manipulation functions.

You can access the strings using both C-style strings and buffers. The former is easier, but is not binary safe: you cannot write binary strings with embedded nulls this way, and DQCsim will throw an error if you try to read a binary string with embedded nulls.

String-style access

dqcs_arb_get_str()

Returns the unstructured string argument at the specified index.

char *dqcs_arb_get_str(
    dqcs_handle_t arb,
    ssize_t index
)

On success, this returns a newly allocated string containing the JSON string. Free it with free() when you're done with it to avoid memory leaks. On failure, this returns NULL.

dqcs_arb_insert_str()

Inserts an unstructured string argument into the list at the specified index.

dqcs_return_t dqcs_arb_insert_str(
    dqcs_handle_t arb,
    ssize_t index,
    const char *s
)

dqcs_arb_pop_str()

Pops an unstructured string argument from the back of the list.

char *dqcs_arb_pop_str(dqcs_handle_t arb)

On success, this returns a newly allocated string containing the JSON string. Free it with free() when you're done with it to avoid memory leaks. On failure, this returns NULL. If the failure is due to the conversion from binary object to C string (i.e., embedded nulls), the data is still popped and is thus lost.

dqcs_arb_push_str()

Pushes an unstructured string argument to the back of the list.

dqcs_return_t dqcs_arb_push_str(
    dqcs_handle_t arb,
    const char *s
)

dqcs_arb_set_str()

Replaces the unstructured argument at the specified index with the specified string.

dqcs_return_t dqcs_arb_set_str(
    dqcs_handle_t arb,
    ssize_t index,
    const char *s
)

Buffer-style access

dqcs_arb_get_raw()

Returns the unstructured string argument at the specified index.

ssize_t dqcs_arb_get_raw(
    dqcs_handle_t arb,
    ssize_t index,
    void *obj,
    size_t obj_size
)

If the actual size of the object differs from the specified object size, this function will copy the minimum of the actual and specified sizes number of bytes, and return what the actual size was.

If the specified object size is zero, obj is allowed to be NULL. You can use this to determine the size of the argument prior to actually reading it, so you can allocate the right buffer size first.

This function returns -1 on failure.

dqcs_arb_insert_raw()

Inserts an unstructured raw argument into the list at the specified index.

dqcs_return_t dqcs_arb_insert_raw(
    dqcs_handle_t arb,
    ssize_t index,
    const void *obj,
    size_t obj_size
)

dqcs_arb_pop_raw()

Pops an unstructured raw argument from the back of the list.

ssize_t dqcs_arb_pop_raw(
    dqcs_handle_t arb,
    void *obj,
    size_t obj_size
)

If the actual size of the object differs from the specified object size, this function will copy the minimum of the actual and specified sizes number of bytes, and return what the actual size was.

If the specified object size is zero, obj is allowed to be NULL. You can use this if you don't need the contents of the argument and just want to delete it.

Since this function removes the returned element, data will be lost if the specified size is smaller than the actual size. To avoid this, first use dqcs_arb_get_size(handle, -1) to query the size.

This function returns -1 on failure. If this is due to a NULL buffer being passed, the data that was popped is lost.

dqcs_arb_push_raw()

Pushes an unstructured raw argument to the back of the list.

dqcs_return_t dqcs_arb_push_raw(
    dqcs_handle_t arb,
    const void *obj,
    size_t obj_size
)

dqcs_arb_set_raw()

Replaces the unstructured argument at the specified index with the specified raw object.

dqcs_return_t dqcs_arb_set_raw(
    dqcs_handle_t arb,
    ssize_t index,
    const void *obj,
    size_t obj_size
)

Miscellaneous list manipulation

dqcs_arb_clear()

Clears the unstructured argument list.

dqcs_return_t dqcs_arb_clear(dqcs_handle_t arb)

dqcs_arb_get_size()

Returns the size in bytes of the unstructured string argument at the specified index.

ssize_t dqcs_arb_get_size(
    dqcs_handle_t arb,
    ssize_t index
)

Returns -1 when the function fails.

dqcs_arb_len()

Returns the number of unstructured arguments, or -1 to indicate failure.

ssize_t dqcs_arb_len(dqcs_handle_t arb)

dqcs_arb_pop()

Pops an unstructured argument from the back of the list without returning it.

dqcs_return_t dqcs_arb_pop(dqcs_handle_t arb)

dqcs_arb_remove()

Removes the specified unstructured string argument from the list.

dqcs_return_t dqcs_arb_remove(
    dqcs_handle_t arb,
    ssize_t index
)