/** * @file * This file defines a class for message bus data types and values */ /****************************************************************************** * Copyright AllSeen Alliance. All rights reserved. * * Permission to use, copy, modify, and/or distribute this software for any * purpose with or without fee is hereby granted, provided that the above * copyright notice and this permission notice appear in all copies. * * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ******************************************************************************/ #ifndef _ALLJOYN_C_MSGARG_H #define _ALLJOYN_C_MSGARG_H #include #include #include #ifdef __cplusplus extern "C" { #endif /** * Definition for a message arg. * alljoyn_msgarg deals with the message bus types and the operations on them. * * alljoyn_msgargs are designed to be light-weight. An alljoyn_msgarg will normally hold references to * the data (strings etc.) it wraps and will only copy that data if the alljoyn_msgarg is copied. For * example no additional memory is allocated for an #ALLJOYN_STRING that references an existing * const char*. If an alljoyn_msgarg is copied using the alljoyn_msgarg_copy function the destination * receives a copy of the contents of the source. The alljoyn_msgarg_stabilize function can also be * called to explicitly force contents of the alljoyn_msgarg to be copied into the alljoyn_msgarg. */ typedef struct _alljoyn_msgarg_handle* alljoyn_msgarg; /** * Enumeration of the various message arg types. * @remark Most of these map directly to the values used in the * DBus wire protocol but some are specific to the AllJoyn implementation. */ typedef enum { ALLJOYN_INVALID = 0, ///< AllJoyn INVALID typeId ALLJOYN_ARRAY = 'a', ///< AllJoyn array container type ALLJOYN_BOOLEAN = 'b', ///< AllJoyn boolean basic type, @c 0 is @c FALSE and @c 1 is @c TRUE - Everything else is invalid ALLJOYN_DOUBLE = 'd', ///< AllJoyn IEEE 754 double basic type ALLJOYN_DICT_ENTRY = 'e', ///< AllJoyn dictionary or map container type - an array of key-value pairs ALLJOYN_SIGNATURE = 'g', ///< AllJoyn signature basic type ALLJOYN_HANDLE = 'h', ///< AllJoyn socket handle basic type ALLJOYN_INT32 = 'i', ///< AllJoyn 32-bit signed integer basic type ALLJOYN_INT16 = 'n', ///< AllJoyn 16-bit signed integer basic type ALLJOYN_OBJECT_PATH = 'o', ///< AllJoyn Name of an AllJoyn object instance basic type ALLJOYN_UINT16 = 'q', ///< AllJoyn 16-bit unsigned integer basic type ALLJOYN_STRUCT = 'r', ///< AllJoyn struct container type ALLJOYN_STRING = 's', ///< AllJoyn UTF-8 NULL terminated string basic type ALLJOYN_UINT64 = 't', ///< AllJoyn 64-bit unsigned integer basic type ALLJOYN_UINT32 = 'u', ///< AllJoyn 32-bit unsigned integer basic type ALLJOYN_VARIANT = 'v', ///< AllJoyn variant container type ALLJOYN_INT64 = 'x', ///< AllJoyn 64-bit signed integer basic type ALLJOYN_BYTE = 'y', ///< AllJoyn 8-bit unsigned integer basic type ALLJOYN_STRUCT_OPEN = '(', /**< Never actually used as a typeId: specified as ALLJOYN_STRUCT */ ALLJOYN_STRUCT_CLOSE = ')', /**< Never actually used as a typeId: specified as ALLJOYN_STRUCT */ ALLJOYN_DICT_ENTRY_OPEN = '{', /**< Never actually used as a typeId: specified as ALLJOYN_DICT_ENTRY */ ALLJOYN_DICT_ENTRY_CLOSE = '}', /**< Never actually used as a typeId: specified as ALLJOYN_DICT_ENTRY */ ALLJOYN_BOOLEAN_ARRAY = ('b' << 8) | 'a', ///< AllJoyn array of booleans ALLJOYN_DOUBLE_ARRAY = ('d' << 8) | 'a', ///< AllJoyn array of IEEE 754 doubles ALLJOYN_INT32_ARRAY = ('i' << 8) | 'a', ///< AllJoyn array of 32-bit signed integers ALLJOYN_INT16_ARRAY = ('n' << 8) | 'a', ///< AllJoyn array of 16-bit signed integers ALLJOYN_UINT16_ARRAY = ('q' << 8) | 'a', ///< AllJoyn array of 16-bit unsigned integers ALLJOYN_UINT64_ARRAY = ('t' << 8) | 'a', ///< AllJoyn array of 64-bit unsigned integers ALLJOYN_UINT32_ARRAY = ('u' << 8) | 'a', ///< AllJoyn array of 32-bit unsigned integers ALLJOYN_INT64_ARRAY = ('x' << 8) | 'a', ///< AllJoyn array of 64-bit signed integers ALLJOYN_BYTE_ARRAY = ('y' << 8) | 'a', ///< AllJoyn array of 8-bit unsigned integers ALLJOYN_WILDCARD = '*' ///< This never appears in a signature but is used for matching arbitrary message args } alljoyn_typeid; /** * Create a new message argument. * calling alljoyn_msgarg_create() is the same as calling * alljoyn_msgarg_array_create(1). * * @return the created message argument */ extern AJ_API alljoyn_msgarg AJ_CALL alljoyn_msgarg_create(); /** * Build a message argument that has its value already set. If the setting the * message argument value fails for any reason the message argument type will be * set to #ALLJOYN_INVALID. See the description of the #alljoyn_msgarg_set() function * for information about the signature and parameters. For initializing complex * values it is recommended to use the alljoyn_msgarg_create and alljoyn_msgarg_set * functions so the success of setting the value can be explicitly checked. * * @param signature The signature for alljoyn_msgarg value. * @param ... One or more values to initialize the alljoyn_msgarg. * * @return the created alljoyn_msgarg */ extern AJ_API alljoyn_msgarg CDECL_CALL alljoyn_msgarg_create_and_set(const char* signature, ...); /** * Destroy a message argument. * * @param arg The message argument to destroy. */ extern AJ_API void AJ_CALL alljoyn_msgarg_destroy(alljoyn_msgarg arg); /** * Create an array of message arguments * * This returns and alljoyn_msgarg however the individual array elements can only * be accessed using alljoyn_msgarg_array_element() function. * * the alljoyn_msgarg returned can be used in any functions that states says * alljoyn_msgarg_array_*. and alljoyn_msgarg created using alljoyn_msgarg_create() * is an array of message arguments with size of 1. * * If the function does not specifically say it is for an array it is assumed that * the message argument was created using alljoyn_msgarg_create() and will be treated * like an array with only one element. * * For example the following code would only copy the first msgarg in the array. * An alljoyn_msgarg of the string "hello". Not both array elements. * * @code * alljoyn_msgarg args = alljoyn_msgarg_array_create(2); * alljoyn_msgarg_array_set(args, 2, "ss", "hello", "world"); * alljoyn_msgarg arg = alljoyn_msgarg_copy(args); * @endcode * * To make a copy of an alljoyn_msgarg that contains an array of elements requires * a for loop. * * @code * alljoyn_msgarg args = alljoyn_msgarg_array_create(2); * alljoyn_msgarg_array_set(args, 2, "ss", "hello", "world"); * alljoyn_msgarg cp_args = alljoyn_msgarg_array_create(2); * for (size_t i = 0; i < 2; ++i) { * alljoyn_msgarg_array_element(cp_args, i) = alljoyn_msgarg_copy(alljoyn_msgarg_array_element(args, i)); * } * @endcode * * @param size the size of the array of alljoyn_msgargs * * @return the created array of message arguments */ extern AJ_API alljoyn_msgarg AJ_CALL alljoyn_msgarg_array_create(size_t size); /** * when working with an array of message arguments this will return the nth item * in the array. * @param arg the alljoyn_msgarg that contains an array of msgargs * @param index the index number of the element we wish to access. * * @return the individual alljoyn_msgarg specified by the index */ extern AJ_API alljoyn_msgarg AJ_CALL alljoyn_msgarg_array_element(alljoyn_msgarg arg, size_t index); /** * Set value of a message arg from a signature and a list of values. Note that any values or * alljoyn_msgarg pointers passed in must remain valid until this alljoyn_msgarg is freed using * alljoyn_msgarg_delete. * * - @c 'a' The array length followed by: * - If the element type is a basic type a pointer to an array of values of that type. * - If the element type is string a pointer to array of const char*, if array length is * non-zero, and the char* pointer is NULL, the NULL must be followed by a pointer to * an array of const qcc::String. * - If the element type is an @ref ALLJOYN_ARRAY "ARRAY", @ref ALLJOYN_STRUCT "STRUCT", * @ref ALLJOYN_DICT_ENTRY "DICT_ENTRY" or @ref ALLJOYN_VARIANT "VARIANT" a pointer to an * array of alljoyn_msgargs where each alljoyn_msgarg has the signature specified by the * element type. * - If the element type is specified using the wildcard character '*', a pointer to * an array of alljoyn_msgargs. The array element type is determined from the type of the * first alljoyn_msgarg in the array, all the elements must have the same type. * - @c 'b' A bool value * - @c 'd' A double (64 bits) * - @c 'g' A pointer to a NUL terminated string (pointer must remain valid for lifetime of the alljoyn_msgarg) * - @c 'h' A qcc::SocketFd * - @c 'i' An int (32 bits) * - @c 'n' An int (16 bits) * - @c 'o' A pointer to a NUL terminated string (pointer must remain valid for lifetime of the alljoyn_msgarg) * - @c 'q' A uint (16 bits) * - @c 's' A pointer to a NUL terminated string (pointer must remain valid for lifetime of the alljoyn_msgarg) * - @c 't' A uint (64 bits) * - @c 'u' A uint (32 bits) * - @c 'v' Not allowed, the actual type must be provided. * - @c 'x' An int (64 bits) * - @c 'y' A byte (8 bits) * * - @c '(' and @c ')' The list of values that appear between the parentheses using the notation above * - @c '{' and @c '}' A pair values using the notation above. * * - @c '*' A pointer to an alljoyn_msgarg. * * Examples: * * An array of strings * * @code * char* fruits[3] = { "apple", "banana", "orange" }; * alljoyn_msgarg bowl; * bowl = alljoyn_msgarg_create(); * alljoyn_msgarg_set(bowl, "as", 3, fruits); * @endcode * * A struct with a uint and two string elements. * * @code alljoyn_msgarg_set(arg, "(uss)", 1024, "hello", "world"); @endcode * * An array of 3 dictionary entries where each entry has an integer key and string value. * * @code * alljoyn_msgarg dict = alljoyn_msgarg_array_create(3) * alljoyn_msgarg_set(alljoyn_msgarg_array_element(0), "{is}", 1, "red"); * alljoyn_msgarg_set(alljoyn_msgarg_array_element(1), "{is}", 2, "green"); * alljoyn_msgarg_set(alljoyn_msgarg_array_element(2), "{is}", 3, "blue"); * alljoyn_msgarg arg = alljoyn_msgarg_create(); * alljoyn_msgarg_set(arg, "a{is}", 3, dict); * @endcode * * An array of uint_16's * * @code * uint16_t aq[] = { 1, 2, 3, 5, 6, 7 }; * alljoyn_msgarg_set(arg, "aq", sizeof(aq) / sizeof(uint16_t), aq); * @endcode * * @param arg The alljoyn_msgarg being set * @param signature The signature for alljoyn_msgarg value * @param ... One or more values to initialize the alljoyn_msgarg. * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus CDECL_CALL alljoyn_msgarg_set(alljoyn_msgarg arg, const char* signature, ...); /** * Matches a signature to the alljoyn_msgarg and if the signature matches unpacks the component * values of an alljoyn_msgarg. Note that the values returned are references into the * alljoyn_msgarg itself so unless copied will become invalid if the alljoyn_msgarg is freed or * goes out of scope. This function resolves through variants, so if the alljoyn_msgarg is a * variant that references a 32 bit integer it can be unpacked directly into a 32 bit integer * pointer. * * - @c 'a' A pointer to a length of type size_t that returns the number of elements in the array followed by: * - If the element type is a scalar type a pointer to a pointer of the correct type for the values. * - Otherwise a pointer to a pointer to an alljoyn_msgarg. * * - @c 'b' A pointer to a bool * - @c 'd' A pointer to a double (64 bits) * - @c 'g' A pointer to a char* (character string is valid for the lifetime of the alljoyn_msgarg) * - @c 'h' A pointer to a qcc::SocketFd * - @c 'i' A pointer to a uint32_t * - @c 'n' A pointer to an int16_t * - @c 'o' A pointer to a char* (character string is valid for the lifetime of the alljoyn_msgarg) * - @c 'q' A pointer to a uint16_t * - @c 's' A pointer to a char* (character string is valid for the lifetime of the alljoyn_msgarg) * - @c 't' A pointer to a uint64_t * - @c 'u' A pointer to a uint32_t * - @c 'v' A pointer to a pointer to an alljoyn_msgarg, matches to a variant but returns a pointer to * the alljoyn_msgarg of the underlying real type. * - @c 'x' A pointer to an int64_t * - @c 'y' A pointer to a uint8_t * * - @c '(' and @c ')' A list of pointers as required for each of the struct members. * - @c '{' and @c '}' Pointers as required for the key and value members. * * - @c '*' A pointer to a pointer to an alljoyn_msgarg. This matches any value type. * * Examples: * * A struct with and uint32 and two string elements. * * @code * struct { * uint32_t i; * char *hello; * char *world; * } myStruct; * alljoyn_msgarg_get(arg, "(uss)", &myStruct.i, &myStruct.hello, &myStruct.world); * @endcode * * A variant where it is known that the value is a uint32, a string, or double. Note that the * variant is resolved away. * * @code * uint32_t i; * double d; * char *str; * QStatus status = alljoyn_msgarg_get(arg, "i", &i); * if (status == ER_BUS_SIGNATURE_MISMATCH) { * status = alljoyn_msgarg_get(arg, "s", &str); * if (status == ER_BUS_SIGNATURE_MISMATCH) { * status = alljoyn_msgarg_get(arg, "d", &d); * } * } * @endcode * * An array of dictionary entries where each entry has an integer key and variant. Find the * entries where the variant value is a string or a struct of 2 strings. * * @code * alljoyn_msgarg entries; * size_t num; * alljoyn_msgarg_get(arg, "a{iv}", &num, &entries); * for (size_t i = 0; i < num; ++i) { * char *str1; * char *str2; * uint32_t key; * status = alljoyn_msgarg_get(alljoyn_msgarg_array_element(entries, i), "{is}", &key, &str1); * if (status == ER_BUS_SIGNATURE_MISMATCH) { * status = alljoyn_msgarg_get(alljoyn_msgarg_array_element(entries, i), "{i(ss)}", &key, &str1, &str2); * } * } * @endcode * * An array of uint_16's * * @code * uint16_t *vals; * size_t numVals; * alljoyn_msgarg_get(arg, "aq", &numVals, &vals); * @endcode * * @param arg The alljoyn_msgarg we are reading from * @param signature The signature for alljoyn_msgarg value * @param ... Pointers to return the unpacked values. * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus CDECL_CALL alljoyn_msgarg_get(alljoyn_msgarg arg, const char* signature, ...); /** * create a copy of a message argument. This will create a new alljoyn_msgarg and * must be cleaned up using alljoyn_msgarg_detroy. * * @param source the alljoyn_msgarg to be copied * * @return copy of the source message argument is returned */ extern AJ_API alljoyn_msgarg AJ_CALL alljoyn_msgarg_copy(const alljoyn_msgarg source); /** * Copy the contents of the source alljoyn_msgarg into the Destination alljoyn_msgarg. If the * destination already contains information it will be cleared before the source * alljoyn_msgarg is copied in. * * @param destination the alljoyn_msgarg that will hold the copy * @param source the alljoyn_msgarg to be copied */ extern AJ_API void AJ_CALL alljoyn_msgarg_clone(alljoyn_msgarg destination, const alljoyn_msgarg source); /** * Equality operator. * * @param lhv The alljoyn_msgarg to compare. * @param rhv The other alljoyn_msgarg to compare * * @return Returns true if the two message args have the same signatures and values. */ extern AJ_API QCC_BOOL AJ_CALL alljoyn_msgarg_equal(alljoyn_msgarg lhv, alljoyn_msgarg rhv); /** * Set an array of alljoyn_msgargs by applying the alljoyn_msgarg_set() function to each alljoyn_msgarg in turn. * * @param args An array of alljoyn_msgargs to set. * @param numArgs [in,out] On input the size of the args array. On output the number of alljoyn_msgargs * that were set. There must be at least enough alljoyn_msgargs to completely * initialize the signature. * * @param signature The signature for alljoyn_msgarg values * @param ... One or more values to initialize the alljoyn_msgarg list. * * @return * - #ER_OK if the alljoyn_msgargs were successfully set. * - #ER_BUS_TRUNCATED if the signature was longer than expected. * - Other error status codes indicating a failure. */ extern AJ_API QStatus CDECL_CALL alljoyn_msgarg_array_set(alljoyn_msgarg args, size_t* numArgs, const char* signature, ...); /** * Unpack an array of alljoyn_msgargs by applying the alljoyn_msgarg_get() function to each alljoyn_msgarg in turn. * * @param args An array of alljoyn_msgargs to unpack. * @param numArgs The size of the alljoyn_msgargs array. * @param signature The signature to match against the alljoyn_msgarg values * @param ... Pointers to return references to the unpacked values. * * @return * - #ER_OK if the alljoyn_msgargs were successfully set. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - Other error status codes indicating a failure. */ extern AJ_API QStatus CDECL_CALL alljoyn_msgarg_array_get(const alljoyn_msgarg args, size_t numArgs, const char* signature, ...); /** * Returns an XML string representation of this type * * @param[in] arg The message arg to generate the XML string representation of * @param[out] str The character string that will hold the XML string * representation of the alljoyn_msgarg * @param[in] buf The size of the char* array that will hold the string * @param[in] indent Number of spaces to indent the generated xml (default value 0) * * @return The number of characters (including the terminating nul byte) which * would have been written to the final string if enough space * available. Thus returning a value of buf or larger means the output * was truncated. */ extern AJ_API size_t AJ_CALL alljoyn_msgarg_tostring(alljoyn_msgarg arg, char* str, size_t buf, size_t indent); /** * Returns an XML string representation for an array of message args. * * @param[in] args The message arg array to generate the XML string representation of * @param[in] numArgs The size of the message arg array. * @param[out] str The character string that will hold the XML string * representation of the alljoyn_msgarg array * @param[in] buf The size of the char* array that will hold the string * @param[in] indent Number of spaces to indent the generated xml (default value 0) * * @return The number of characters (including the terminating nul byte) which * would have been written to the final string if enough space is * available. Thus returning a value of buf or larger means the output * was truncated. */ extern AJ_API size_t AJ_CALL alljoyn_msgarg_array_tostring(const alljoyn_msgarg args, size_t numArgs, char* str, size_t buf, size_t indent); /** * Returns a string for the signature of this value * * @param[in] arg the argument to read the signature from * @param[out] str a string containing the signature of the alljoyn_msgarg use NULL pointer * to find string size. * @param[in] buf The size of the char* array that will hold the string * * @return The number of characters (including the terminating nul byte) which * would have been written to the final string if enough space is * available. Thus returning a value of buf or larger means the output * was truncated. */ extern AJ_API size_t AJ_CALL alljoyn_msgarg_signature(alljoyn_msgarg arg, char* str, size_t buf); /** * Returns a string representation of the signature of an array of message args. * * @param[in] values A pointer to an array of message arg values * @param[in] numValues Length of the array * @param[out] str a string containing the signature of the alljoyn_msgarg use NULL * pointer to find string size. * @param[in] buf The size of the char* array that will hold the string * * @return The number of characters (including the terminating nul byte) which * would have been written to the final string if enough space is * available. Thus returning a value of buf or larger means the output * was truncated. */ extern AJ_API size_t AJ_CALL alljoyn_msgarg_array_signature(alljoyn_msgarg values, size_t numValues, char* str, size_t buf); /** * Checks the signature of this arg. * * @param arg The message argument we want to check the signature of * @param signature The signature to check * * @return true if this arg has the specified signature, otherwise returns false. */ extern AJ_API QCC_BOOL AJ_CALL alljoyn_msgarg_hassignature(alljoyn_msgarg arg, const char* signature); /** * Helper function for accessing dictionary elements. The alljoyn_msgarg must be an array of dictionary * elements. The second parameter is the key value, this is expressed according to the rules for * alljoyn_msgarg_set so is either a scalar, a pointer to a string, or for 64 bit values a pointer to * the value. This value is matched against the dictionary array to locate the matching element. * The third and subsequent parameters are unpacked according to the rules of alljoyn_msgarg_get. * * For example, where the key is a string and the values are structs: * * @code * uint8_t age; * uint32_t height; * const char* address; * QStatus status = alljoyn_msgarg_getdictelement(arg, "{s(yus)}", "fred", &age, &height, &address); * @endcode * * This function is particularly useful for extracting specific properties from the array of property * values returned by ProxyBusObject::GetAllProperties. * * @param arg a message argument containing an array of dictionary elements * @param elemSig The expected signature for the dictionary element, e.g. "{su}" * @param ... Pointers to return unpacked key values. * * @return * - #ER_OK if the dictionary signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_NOT_A_DICTIONARY if this function is called on an alljoyn_msgarg that is not a dictionary. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - #ER_BUS_ELEMENT_NOT_FOUND if the key was not found in the dictionary. * - An error status otherwise */ extern AJ_API QStatus CDECL_CALL alljoyn_msgarg_getdictelement(alljoyn_msgarg arg, const char* elemSig, ...); /** * Get the alljoyn_typeid of the alljoyn_msgarg * * @param arg the message argument we want to know the alljoyn_typeid of. * * @return the alljoyn_typeid of the alljoyn_msgarg */ extern AJ_API alljoyn_typeid AJ_CALL alljoyn_msgarg_gettype(alljoyn_msgarg arg); /** * Clear the alljoyn_msgarg setting the type to ALLJOYN_INVALID and freeing any memory allocated for the * alljoyn_msgarg value. * * @param arg the message argument to be cleared. */ extern AJ_API void AJ_CALL alljoyn_msgarg_clear(alljoyn_msgarg arg); /** * Makes an alljoyn_msgarg stable by completely copying the contents into locally * managed memory. After an alljoyn_msgarg has been stabilized any values used to * initialize or set the message arg can be freed. * * @param arg the message argument to stabilize */ extern AJ_API void AJ_CALL alljoyn_msgarg_stabilize(alljoyn_msgarg arg); /// @cond ALLJOYN_DEV /* ******************************************************************************* * This set of functions were originally designed for the alljoyn_unity bindings * however they did not not properly map with the C++ MsgArg Class. * * No Functions below this point should be used by any code except for the * AllJoyn Unity Extension. The functions could be changed at any time. ******************************************************************************* */ /** * Set an array of alljoyn_msgargs by applying the alljoyn_msgarg_set() function * to each alljoyn_msgarg in turn. * * @param args An array of alljoyn_msgargs to set. * @param argOffset Offset from the start of the alljoyn_msgarg array. * @param numArgs [in,out] On input the number of args to set. On output the number of alljoyn_msgargs * that were set. There must be at least enough alljoyn_msgargs to completely * initialize the signature. * there should at least enough. * @param signature The signature for alljoyn_msgarg values * @param ... One or more values to initialize the alljoyn_msgarg list. * * @return * - #ER_OK if the alljoyn_msgargs were successfully set. * - #ER_BUS_TRUNCATED if the signature was longer than expected. * - Other error status codes indicating a failure. */ extern AJ_API QStatus CDECL_CALL alljoyn_msgarg_array_set_offset(alljoyn_msgarg args, size_t argOffset, size_t* numArgs, const char* signature, ...); /** * This function is identical to alljoyn_msgarg_set except after the values * in the message arg have been set the alljoyn_msgarg will be stabilized. * This is useful when the call is made from a manage language like C sharp where * objects like strings may be garbage collected. * * @param arg The alljoyn_msgarg being set * @param signature The signature for alljoyn_msgarg value * @param ... One or more values to initialize the alljoyn_msgarg. * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus CDECL_CALL alljoyn_msgarg_set_and_stabilize(alljoyn_msgarg arg, const char* signature, ...); /******************************************************************************* * MsgArg set functions for each of the basic data types *******************************************************************************/ /** * Set the value of an alljoyn_msgarg to hold an uint8 (byte). * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg that will hold the uint8 (byte) * @param y a uint8 * * @return * - #ER_OK if the alljoyn_msgarg walljoyn_msgargcessfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_uint8(alljoyn_msgarg arg, uint8_t y); /** * Set the value of an alljoyn_msgarg to hold a QCC_BOOL. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg that will hold the QCC_BOOL * @param b a QCC_BOOL * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_bool(alljoyn_msgarg arg, QCC_BOOL b); /** * Set the value of an alljoyn_msgarg to hold an int16. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg that will hold the int16 * @param n an int16 * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_int16(alljoyn_msgarg arg, int16_t n); /** * Set the value of an alljoyn_msgarg to hold an uint16. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg that will hold the uint16 * @param q an uint16 * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_uint16(alljoyn_msgarg arg, uint16_t q); /** * Set the value of an alljoyn_msgarg to hold an int32. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg that will hold the int32 * @param i an int32 * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_int32(alljoyn_msgarg arg, int32_t i); /** * Set the value of an alljoyn_msgarg to hold an uint32. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg that will hold the uint32 * @param u an uint32 * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_uint32(alljoyn_msgarg arg, uint32_t u); /** * Set the value of an alljoyn_msgarg to hold an int64. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg that will hold the int64 * @param x an int64 * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_int64(alljoyn_msgarg arg, int64_t x); /** * Set the value of an alljoyn_msgarg to hold an uint64. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg that will hold the uint64 * @param t an uint64 * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_uint64(alljoyn_msgarg arg, uint64_t t); /** * Set the value of an alljoyn_msgarg to hold an double. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg that will hold the double * @param d an double * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_double(alljoyn_msgarg arg, double d); /** * Set the value of an alljoyn_msgarg to hold a string. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg that will hold the string * @param s an string * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_string(alljoyn_msgarg arg, const char* s); /** * Set the value of an alljoyn_msgarg to hold an object path * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg that will hold the object path * @param o an object path string * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_objectpath(alljoyn_msgarg arg, const char* o); /** * Set the value of an alljoyn_msgarg to hold a signature. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg that will hold the signature * @param g a signature string * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_signature(alljoyn_msgarg arg, const char* g); /******************************************************************************* * MsgArg get functions for each of the basic data types *******************************************************************************/ /** * Get an uint8 (bytes) from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] y a pointer to the uint8 (byte) * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_uint8(const alljoyn_msgarg arg, uint8_t* y); /** * Get a QCC_BOOL from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] b a pointer to the QCC_BOOL * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_bool(const alljoyn_msgarg arg, QCC_BOOL* b); /** * Get an int16 from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] n a pointer to the int16 * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_int16(const alljoyn_msgarg arg, int16_t* n); /** * Get an uint16 from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] q a pointer to the uint16 * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_uint16(const alljoyn_msgarg arg, uint16_t* q); /** * Get an int32 from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] i a pointer to the int32 * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_int32(const alljoyn_msgarg arg, int32_t* i); /** * Get an uint32 from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] u a pointer to the uint32 * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_uint32(const alljoyn_msgarg arg, uint32_t* u); /** * Get an int64 from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] x a pointer to the int64 * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_int64(const alljoyn_msgarg arg, int64_t* x); /** * Get an uint64 from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] t a pointer to the uint64 * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_uint64(const alljoyn_msgarg arg, uint64_t* t); /** * Get a double from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] d a pointer to the double * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_double(const alljoyn_msgarg arg, double* d); /** * Get a string from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] s a pointer to the string * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_string(const alljoyn_msgarg arg, char** s); /** * Get an object path from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] o a pointer to the object path string * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_objectpath(const alljoyn_msgarg arg, char** o); /** * Get a signature from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] g a pointer to the signature string * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_signature(const alljoyn_msgarg arg, char** g); /** * Get the alljoyn_msgarg from an variant alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] v the alljoyn_msgarg that will be returned * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_variant(const alljoyn_msgarg arg, alljoyn_msgarg v); /******************************************************************************* * MsgArg set function for arrays of each basic data type *******************************************************************************/ /** * Set the value of an alljoyn_msgarg to hold an array of uint8s (bytes). * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg to set * @param length the size of the array of uint8s (bytes) * @param ay a pointer to an array of uint8s (bytes) * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_uint8_array(alljoyn_msgarg arg, size_t length, uint8_t* ay); /** * Set the value of an alljoyn_msgarg to hold an array of QCC_BOOLs. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg to set * @param length the size of the array of QCC_BOOLs * @param ab a pointer to an array of QCC_BOOLs * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_bool_array(alljoyn_msgarg arg, size_t length, QCC_BOOL* ab); /** * Set the value of an alljoyn_msgarg to hold an array of int16s. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg to set * @param length the size of the array of int16s * @param an a pointer to an array of int16s * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_int16_array(alljoyn_msgarg arg, size_t length, int16_t* an); /** * Set the value of an alljoyn_msgarg to hold an array of uint16s. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg to set * @param length the size of the array of uint16s * @param aq a pointer to an array of uint16s * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_uint16_array(alljoyn_msgarg arg, size_t length, uint16_t* aq); /** * Set the value of an alljoyn_msgarg to hold an array of int32s. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg to set * @param length the size of the array of int32s * @param ai a pointer to an array of int32s * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_int32_array(alljoyn_msgarg arg, size_t length, int32_t* ai); /** * Set the value of an alljoyn_msgarg to hold an array of uint32s. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg to set * @param length the size of the array of uint32s * @param au a pointer to an array of uint32s * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_uint32_array(alljoyn_msgarg arg, size_t length, uint32_t* au); /** * Set the value of an alljoyn_msgarg to hold an array of int64s. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg to set * @param length the size of the array of int64s * @param ax a pointer to an array of int64s * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_int64_array(alljoyn_msgarg arg, size_t length, int64_t* ax); /** * Set the value of an alljoyn_msgarg to hold an array of uint64s. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg to set * @param length the size of the array of uint64s * @param at a pointer to an array of uint64s * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_uint64_array(alljoyn_msgarg arg, size_t length, uint64_t* at); /** * Set the value of an alljoyn_msgarg to hold an array of doubles. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg to set * @param length the size of the array of dobules * @param ad a pointer to an array of doubles * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_double_array(alljoyn_msgarg arg, size_t length, double* ad); /** * Set the value of an alljoyn_msgarg to hold an array of strings. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg to set * @param length the size of the array of object paths * @param as a pointer to an array of object paths * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_string_array(alljoyn_msgarg arg, size_t length, const char** as); /** * Set the value of an alljoyn_msgarg to hold an array of object paths. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg to set * @param length the size of the array of object paths * @param ao a pointer to an array of object paths * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_objectpath_array(alljoyn_msgarg arg, size_t length, const char** ao); /** * Set the value of an alljoyn_msgarg to hold an array of signatures. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * * @param arg the alljoyn_msgarg to set * @param[out] length the size of the array of signatures * @param[out] ag a pointer to an array of signatures * * @return * - #ER_OK if the alljoyn_msgarg was successfully set * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_set_signature_array(alljoyn_msgarg arg, size_t length, const char** ag); /******************************************************************************* * MsgArg get function for arrays of each basic data type *******************************************************************************/ /** * get an array of uint8s (bytes) from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] length the size of the uint8 (byte) array * @param[out] ay a pointer to the uint8 (byte) array * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_uint8_array(const alljoyn_msgarg arg, size_t* length, uint8_t* ay); /** * get an array of QCC_BOOLs from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] length the size of the QCC_BOOL array * @param[out] ab a pointer to the QCC_BOOL array * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_bool_array(const alljoyn_msgarg arg, size_t* length, QCC_BOOL* ab); /** * get an array of int16 from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] length the size of the int16 array * @param[out] an a pointer to the int16 array * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_int16_array(const alljoyn_msgarg arg, size_t* length, int16_t* an); /** * get an array of uint16s from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] length the size of the uint16 array * @param[out] aq a pointer to the uint16 array * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_uint16_array(const alljoyn_msgarg arg, size_t* length, uint16_t* aq); /** * get an array of int32 from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] length the size of the int32 array * @param[out] ai a pointer to the int32 array * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_int32_array(const alljoyn_msgarg arg, size_t* length, int32_t* ai); /** * get an array of uint32 from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] length the size of the uint32 array * @param[out] au a pointer to the uint32 array * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_uint32_array(const alljoyn_msgarg arg, size_t* length, uint32_t* au); /** * get an array of int64s from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] length the size of the int64 array * @param[out] ax a pointer to the int64 array * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_int64_array(const alljoyn_msgarg arg, size_t* length, int64_t* ax); /** * get an array of uint64s from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] length the size of the uint64 array * @param[out] at a pointer to the uint64 array * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_uint64_array(const alljoyn_msgarg arg, size_t* length, uint64_t* at); /** * get an array of doubles from an alljoyn_msgarg * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param[out] length the size of the double array * @param[out] ad a pointer to the double array * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_double_array(const alljoyn_msgarg arg, size_t* length, double* ad); /** * get an array of alljoyn_msgargs from an alljoyn_msgarg. * * This function can be used for any array that contains an array of alljoyn_msgargs. * This would be non-scalar arrays. i.e. as, ao, ag, a{is}, av etc. * * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_get. * * @param arg the alljoyn_msgarg to obtain the data from * @param arg the signature of the array * @param[out] length the size of the array * @param[out] av a pointer to the alljoyn_msgarg array * * @return * - #ER_OK if the signature matched and alljoyn_msgarg was successfully unpacked. * - #ER_BUS_SIGNATURE_MISMATCH if the signature did not match. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_get_variant_array(const alljoyn_msgarg arg, const char* signature, size_t* length, alljoyn_msgarg* av); /******************************************************************************* * MsgArg get functions for Arrays of Arrays *******************************************************************************/ /** * How many elements are in the alljoyn array * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * @see alljoyn_msgarg_get. * * @param arg The alljoyn_msgarg that contains the array elements * * @return the number of elements in the alljoyn_msgarg */ extern AJ_API size_t AJ_CALL alljoyn_msgarg_get_array_numberofelements(const alljoyn_msgarg arg); /** * Obtain a single alljoyn_msgarg element from an array of alljoyn_msgarg elements * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * @see alljoyn_msgarg_get. * * @param arg The alljoyn_msgarg that contains the array element * @param index The index value for the individual alljoyn_msgarg * @param[out] element The alljoyn_msgarg located at the index */ extern AJ_API void AJ_CALL alljoyn_msgarg_get_array_element(const alljoyn_msgarg arg, size_t index, alljoyn_msgarg* element); /** * Obtain the signature of an element inside an array of alljoyn_msgargs * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * @see alljoyn_msgarg_set * @see alljoyn_msgarg_get. * * @param arg The alljoyn_msgarg that contains the signature * @param index The index value for the individual alljoyn_msgarg * * @return the string representing the signature of the element */ extern AJ_API const char* AJ_CALL alljoyn_msgarg_get_array_elementsignature(const alljoyn_msgarg arg, size_t index); /******************************************************************************* * MsgArg functions for dictionaries *******************************************************************************/ /* * Obtain the alljoyn_msgarg used as the key for a key/value pair in an AllJoyn * dictionary entry. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * * @param arg An alljoyn_msgarg that contains a single key/value pair dictionary * entry. * * @return an alljoyn_msgarg containing the key portion of a key/value pair */ extern AJ_API alljoyn_msgarg AJ_CALL alljoyn_msgarg_getkey(alljoyn_msgarg arg); /* * Obtain the alljoyn_msgarg used as the value for a key/value pair in an AllJoyn * dictionary entry. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * * @param arg An alljoyn_msgarg that contains a single key/value pair dictionary * entry. * * @return an alljoyn_msgarg containing the value portion of a key/value pair */ extern AJ_API alljoyn_msgarg AJ_CALL alljoyn_msgarg_getvalue(alljoyn_msgarg arg); /* * Create a key/value pair for an AllJoyn dictionary entry. * * the alljoyn_msgargs used for the key and value will be copied into the arg * and will not be managed by the alljoyn_msgarg arg. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * * @param arg The alljoyn_msgarg to set with a key/value pair * @param key An alljoyn_msgarg containing the key in a key/value pair * @param value An alljoyn_msgarg containing the value in a key/value pair * * @return #ER_OK */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_setdictentry(alljoyn_msgarg arg, alljoyn_msgarg key, alljoyn_msgarg value); /******************************************************************************* * MsgArg functions for structs *******************************************************************************/ /* * Set the values for an AllJoyn Struct entry. * an AllJoyn struct is passed in as an array of alljoyn_msgargs with each element * representing a member of the struct. * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * * @param arg an alljoyn_msgarg that will hold the values of the struct * @param struct_members an alljoyn_msgarg array that represents a struct * @param num_members the number of members in the struct * * @return #ER_OK */ extern AJ_API QStatus AJ_CALL alljoyn_msgarg_setstruct(alljoyn_msgarg arg, alljoyn_msgarg struct_members, size_t num_members); /* * Obtain the number of members in an AllJoyn struct * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * * @param arg the alljoyn_msgarg containing a struct * * @return the number of members contained in the struct */ extern AJ_API size_t AJ_CALL alljoyn_msgarg_getnummembers(alljoyn_msgarg arg); /* * obtain the member of an AllJoyn struct at the index location * @remark This function exists for development of other language bindings and may * be changed or removed in future updates and should not be used for reading * values from an alljoyn_msgarg. * * @param arg the alljoyn_msgarg containing a struct * @param index the index of the member * * @return the alljoyn_msgarg at the index */ extern AJ_API alljoyn_msgarg AJ_CALL alljoyn_msgarg_getmember(alljoyn_msgarg arg, size_t index); /// @endcond #ifdef __cplusplus } /* extern "C" */ #endif #endif