/** * @file * alljoyn_aboutobjectdescription holds a list of the bus object interfaces and their paths. */ /****************************************************************************** * 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_ABOUTOBJECTDESCRIPTION_C_H #define _ALLJOYN_ABOUTOBJECTDESCRIPTION_C_H #include #include #ifdef __cplusplus extern "C" { #endif /** * alljoyn_aboutobjectdescription is a helper for accessing the ObjectDescription * alljoyn_msgarg that is sent as part of an announce signal. It contains helper * functions for quickly determining if an alljoyn_aboutobjectdescription * contains a specified path or interface. */ typedef struct _alljoyn_aboutobjectdescription_handle* alljoyn_aboutobjectdescription; /** * Allocate a new empty alljoyn_aboutobjectdescription object. * Use the alljoyn_aboutobjectdescription_createfrommsgarg method to fill in data. * * @return The allocated alljoyn_aboutobjectdescription. */ extern AJ_API alljoyn_aboutobjectdescription AJ_CALL alljoyn_aboutobjectdescription_create(); /** * Allocate a new alljoyn_aboutdata object filling in the fields of the About data * using an alljoyn_msgarg. The provided alljoyn_msgarg must contain a dictionary * with signature a{sv} with About data fields. * * If the passed in alljoyn_msgarg is an ill formed About data alljoyn_msgarg this call * will fail silently. If the alljoyn_msgarg does not come from About Announce signal * it is best to create an empty alljoyn_aboutdata object and use the * alljoyn_about_createfrommsgarg function to fill in the About data. * Allocate a new alljoyn_aboutobjectdescription object filling in the data * from an alljoyn_msgarg. * * The alljoyn_msgarg must contain an array of type a(oas) The expected use of this * object is to fill in the object description using an alljoyn_msgarg obtained from * the Announce signal or the GetObjectDescription method from org.alljoyn.About interface. * * If the arg came from the org.alljoyn.About.Announce signal or the * org.alljoyn.AboutGetObjectDescrption method then it can be used to create * the alljoyn_aboutobjectdescription. If the arg came from any other source * it is recommended to create first an empty alljoyn_aboutobjectdescription object * and use the alljoyn_aboutobjectdescription_createfrommsgarg. * * @param arg alljoyn_msgarg contain About Object Description data * * @return The allocated alljoyn_aboutobjectdescription. */ extern AJ_API alljoyn_aboutobjectdescription AJ_CALL alljoyn_aboutobjectdescription_create_full(const alljoyn_msgarg arg); /** * Fill in the ObjectDescription fields using an alljoyn_msgarg * * The alljoyn_msgarg must contain an array of type a(oas) The expected use * of this object is to fill in the ObjectDescription using a MsgArg obtain * from the Announce signal or the GetObjectDescription method from * the org.alljoyn.about interface. * * @param[in] description The alljoyn_aboutobjectdescription object this call is made for * @param[in] arg alljoyn_msgarg contain About data dictionary * * @return ER_OK on success */ extern AJ_API QStatus AJ_CALL alljoyn_aboutobjectdescription_createfrommsgarg(alljoyn_aboutobjectdescription description, const alljoyn_msgarg arg); /** * Free an alljoyn_aboutobjectdescription object. * * @param description The alljoyn_aboutobjectdescription to be freed. */ extern AJ_API void AJ_CALL alljoyn_aboutobjectdescription_destroy(alljoyn_aboutobjectdescription description); /** * Get a list of the paths that are added to this AboutObjectDescription. * * @param[in] description the alljoyn_aboutobjectdescription object this call is made for * @param[out] paths array of paths * @param[in] numPaths the number of paths * * @return * The total number of paths found in the AboutObjectDescription. If this * number is larger than `numPaths` then only `numPaths` of paths will be * returned in the `paths` array. * */ extern AJ_API size_t AJ_CALL alljoyn_aboutobjectdescription_getpaths(alljoyn_aboutobjectdescription description, const char** paths, size_t numPaths); /** * Get a list of interfaces advertised at the given path that are part of * this AboutObjectDescription. * * @param[in] description the alljoyn_aboutobjectdescription object this call is made for * @param[in] path the path we want to get a list of interfaces for * @param[out] interfaces array of interface names * @param[in] numInterfaces number of interface names * * @return * The total number of interfaces found in the AboutObjectDescription for * the specified path. If this number is larger than `numInterfaces` * then only `numInterfaces` of interfaces will be returned in the * `interfaces` array. */ extern AJ_API size_t AJ_CALL alljoyn_aboutobjectdescription_getinterfaces(alljoyn_aboutobjectdescription description, const char* path, const char** interfaces, size_t numInterfaces); /** * Get a list of the paths for a given interface. Its possible to have the * same interface listed under multiple paths. * * @param[in] description the alljoyn_aboutobjectdescription object this call is made for * @param[in] interfaceName the interface we want to get a list of paths for * @param[out] paths array of paths * @param[in] numPaths the number of paths * * @return * The total number of paths found in the AboutObjectDescription for * the specified path. If this number its larger than the `numPaths` * then only `numPaths` of interfaces will be returned in the `paths` * array * */ extern AJ_API size_t AJ_CALL alljoyn_aboutobjectdescription_getinterfacepaths(alljoyn_aboutobjectdescription description, const char* interfaceName, const char** paths, size_t numPaths); /** * Clear all the contents of this AboutObjectDescription * * @param[in] description The alljoyn_aboutobjectdescription object this call is made for * * @return ER_OK */ extern AJ_API void AJ_CALL alljoyn_aboutobjectdescription_clear(alljoyn_aboutobjectdescription description); /** * Returns true if the given path is found * * @param[in] description the alljoyn_aboutobjectdescription object this call is made for * @param[in] path BusObject path * * @return true if the path is found */ extern AJ_API bool AJ_CALL alljoyn_aboutobjectdescription_haspath(alljoyn_aboutobjectdescription description, const char* path); /** * Returns true if the given interface name is found in any path * * @param[in] description the alljoyn_aboutobjectdescription object this call is made for * @param[in] interfaceName the name of the interface you are looking for * * @return true if the interface is found */ extern AJ_API bool AJ_CALL alljoyn_aboutobjectdescription_hasinterface(alljoyn_aboutobjectdescription description, const char* interfaceName); /** * Returns true if the given interface name is found at the given path * * @param[in] description the alljoyn_aboutobjectdescription object this call is made for * @param[in] path path name of the interface * @param[in] interfaceName the name of the interface you are looking for * * @return true if the interface is found at the given path */ extern AJ_API bool AJ_CALL alljoyn_aboutobjectdescription_hasinterfaceatpath(alljoyn_aboutobjectdescription description, const char* path, const char* interfaceName); /** * @param[in] description the alljoyn_aboutobjectdescription object this call is made for * @param[out] msgArg containing a signature a(oas) for an array of object paths and * an array of interfaces found on that object path * * @return ER_OK if successful */ extern AJ_API QStatus AJ_CALL alljoyn_aboutobjectdescription_getmsgarg(alljoyn_aboutobjectdescription description, alljoyn_msgarg msgArg); #ifdef __cplusplus } /* extern "C" */ #endif #endif //_ALLJOYN_ABOUTOBJECTDESCRIPTION_C_H