/** * @file * This file defines the alljoyn_proxybusobject and related functions. * The alljoyn_proxybusobject represents a single object registered on the bus. * alljoyn_proxybusobjects are used to make method calls on these remotely located DBus objects. */ /****************************************************************************** * 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_REMOTEBUSOBJECT_H #define _ALLJOYN_C_REMOTEBUSOBJECT_H #include #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif /** * The alljoyn_proxybusobject represents a single object registered on the bus. * alljoyn_proxybusobjects are used to make method calls on these remotely * located AllJoyn objects. */ typedef struct _alljoyn_proxybusobject_handle* alljoyn_proxybusobject; #ifndef _ALLJOYN_OPAQUE_BUSATTACHMENT_ #define _ALLJOYN_OPAQUE_BUSATTACHMENT_ /** * alljoyn_busattachment is the top level object responsible for connecting to and * managing an AllJoyn message bus */ typedef struct _alljoyn_busattachment_handle* alljoyn_busattachment; #endif /** * Callback registered with alljoyn_proxybusobject_introspectremoteobjectasync() * * @param status ER_OK if successful * @param obj Remote bus object that was introspected * @param context Context passed in IntrospectRemoteObjectAsync() */ typedef void (AJ_CALL * alljoyn_proxybusobject_listener_introspectcb_ptr)(QStatus status, alljoyn_proxybusobject obj, void* context); /** * Callback registered with alljoyn_proxybusobject_getpropertyasync() * * @param status - #ER_OK if the property get request was successfull or: * - #ER_BUS_OBJECT_NO_SUCH_INTERFACE if the specified interfaces does not exist on the remote object. * - #ER_BUS_NO_SUCH_PROPERTY if the property does not exist * - Other error status codes indicating the reason the get request failed. * @param obj Remote bus object that was introspected * @param value If status is ER_OK a MsgArg containing the returned property value * @param context Caller provided context passed in to alljoyn_proxybusobject_getpropertyasync() */ typedef void (AJ_CALL * alljoyn_proxybusobject_listener_getpropertycb_ptr)(QStatus status, alljoyn_proxybusobject obj, const alljoyn_msgarg value, void* context); /** * Callback registered with alljoyn_proxybusobject_getallpropertiesasync() * * @param status - #ER_OK if the get all properties request was successfull or: * - #ER_BUS_OBJECT_NO_SUCH_INTERFACE if the specified interfaces does not exist on the remote object. * - Other error status codes indicating the reason the get request failed. * @param obj Remote bus object that was introspected * @param values If status is ER_OK an array of dictionary entries, signature "a{sv}" listing the properties. * @param context Caller provided context passed in to alljoyn_proxybusobject_getallpropertiesasync() */ typedef void (AJ_CALL * alljoyn_proxybusobject_listener_getallpropertiescb_ptr)(QStatus status, alljoyn_proxybusobject obj, const alljoyn_msgarg values, void* context); /** * Callback registered with alljoyn_proxybusobject_setpropertyasync() * * @param status - ER_OK if the property was successfully set or: * - #ER_BUS_OBJECT_NO_SUCH_INTERFACE if the specified interfaces does not exist on the remote object. * - #ER_BUS_NO_SUCH_PROPERTY if the property does not exist * - Other error status codes indicating the reason the set request failed. * @param obj Remote bus object that was introspected * @param context Caller provided context passed in to alljoyn_proxybusobject_setpropertyasync() */ typedef void (AJ_CALL * alljoyn_proxybusobject_listener_setpropertycb_ptr)(QStatus status, alljoyn_proxybusobject obj, void* context); /** * Callback to receive property changed events. * * @param obj Remote bus object that owns the property that changed. * @param ifaceName Name of the interface that defines the property. * @param changed Property values that changed as an array of dictionary entries, signature "a{sv}". * @param invalidated Properties whose values have been invalidated, signature "as". * @param context Caller provided context passed in to RegisterPropertiesChangedListener */ typedef void (AJ_CALL * alljoyn_proxybusobject_listener_propertieschanged_ptr)(alljoyn_proxybusobject obj, const char* ifaceName, const alljoyn_msgarg changed, const alljoyn_msgarg invalidated, void* context); /** * Create an empty proxy bus object that refers to an object at given remote service name. Note * that the created proxy bus object does not contain information about the interfaces that the * actual remote object implements with the exception that org.freedesktop.DBus.Peer * interface is special-cased (per the DBus spec) and can always be called on any object. Nor * does it contain information about the child objects that the actual remote object might * contain. * * To fill in this object with the interfaces and child object names that the actual remote * object describes in its introspection data, call alljoyn_proxybusobject_introspectremoteobject() or * alljoyn_proxybusobject_introspectremoteobjectasync(). * * @param bus The bus. * @param service The remote service name (well-known or unique). * @param path The absolute (non-relative) object path for the remote object. * @param sessionId The session id the be used for communicating with remote object. * * @return the allocated alljoyn_proxybusobject */ extern AJ_API alljoyn_proxybusobject AJ_CALL alljoyn_proxybusobject_create(alljoyn_busattachment bus, const char* service, const char* path, alljoyn_sessionid sessionId); /** * Create an empty proxy bus object that refers to an object at given remote service name. Note * that the created proxy bus object does not contain information about the interfaces that the * actual remote object implements with the exception that org.freedesktop.DBus.Peer * interface is special-cased (per the DBus spec) and can always be called on any object. Nor * does it contain information about the child objects that the actual remote object might * contain. * * proxybusobjects created using this function will require authentication. * Unless the interfaces security policy is AJ_IFC_SECURITY_OFF. * * To fill in this object with the interfaces and child object names that the actual remote * object describes in its introspection data, call alljoyn_proxybusobject_introspectremoteobject() or * alljoyn_proxybusobject_introspectremoteobjectasync(). * * @param bus The bus. * @param service The remote service name (well-known or unique). * @param path The absolute (non-relative) object path for the remote object. * @param sessionId The session id the be used for communicating with remote object. * * @return the allocated alljoyn_proxybusobject */ extern AJ_API alljoyn_proxybusobject AJ_CALL alljoyn_proxybusobject_create_secure(alljoyn_busattachment bus, const char* service, const char* path, alljoyn_sessionid sessionId); /** * Destroy a proxy object created using alljoyn_proxybusobject_create. * * @param proxyObj The proxy bus object to destroy. */ extern AJ_API void AJ_CALL alljoyn_proxybusobject_destroy(alljoyn_proxybusobject proxyObj); /** * Add an interface to this alljoyn_proxybusobject. * * Occasionally, AllJoyn library user may wish to call a method on * an %alljoyn_proxybusobject that was not reported during introspection of the remote object. * When this happens, the InterfaceDescription will have to be registered with the * Bus manually and the interface will have to be added to the %alljoyn_proxybusobject using this function. * @remark * The interface added via this call must have been previously registered with the * Bus. (i.e. it must have come from a call to alljoyn_busattachment_getinterface). * * @param proxyObj The proxy bus object onto which the interface is to be added. * @param iface The interface to add to this object. Must come from alljoyn_busattachment_getinterface. * @return * - #ER_OK if successful. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_addinterface(alljoyn_proxybusobject proxyObj, const alljoyn_interfacedescription iface); /** * Add an existing interface to this object using the interface's name. * * @param proxyObj The proxy bus object onto which the interface is to be added. * @param name Name of existing interface to add to this object. * @return * - #ER_OK if successful. * - An error status otherwise. */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_addinterface_by_name(alljoyn_proxybusobject proxyObj, const char* name); /** * Returns an array of alljoyn_proxybusobjects for the children of this %alljoyn_proxybusobject. * * @param proxyObj The proxybus object we are getting the children from * @param children An %alljoyn_proxybusobject array to receive the children. Can be NULL in * which case no children are returned and the return value gives the number * of children available. * @param numChildren The size of the %alljoyn_proxybusobject array. If this value is smaller than the total * number of children only numChildren will be returned. * * @return The number of children returned or the total number of children if children is NULL. */ extern AJ_API size_t AJ_CALL alljoyn_proxybusobject_getchildren(alljoyn_proxybusobject proxyObj, alljoyn_proxybusobject* children, size_t numChildren); /** * Get a path descendant alljoyn_proxybusobject (child) by its relative path name. * * For example, if this alljoyn_proxybusobject's path is @c "/foo/bar", then you can * retrieve the alljoyn_proxybusobject for @c "/foo/bar/bat/baz" by calling * @c GetChild("bat/baz") * * @param proxyObj The proxybus object we are getting the descendant from * @param path The relative path for the child. * * @return * - The (potentially deep) descendant alljoyn_proxybusobject * - NULL if not found. */ extern AJ_API alljoyn_proxybusobject AJ_CALL alljoyn_proxybusobject_getchild(alljoyn_proxybusobject proxyObj, const char* path); /** * Add a child object (direct or deep object path descendant) to this object. * If you add a deep path descendant, this function will create intermediate * alljoyn_proxybusobject children as needed. * * @remark * - It is an error to try to add a child that already exists. * - It is an error to try to add a child that has an object path that is not a descendant of this object's path. * * @param proxyObj The proxy bus object onto which the child object is to be added * @param child Child alljoyn_proxybusobject * * @return * - #ER_OK if successful. * - #ER_BUS_BAD_CHILD_PATH if the path is a bad path * - #ER_BUS_OBJ_ALREADY_EXISTS the object already exists on the alljoyn_proxybusobject */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_addchild(alljoyn_proxybusobject proxyObj, const alljoyn_proxybusobject child); /** * Remove a child object and any descendants it may have. * * @param proxyObj The proxy bus object off of which the child object is to be removed * @param path Absolute or relative (to this alljoyn_proxybusobject) object path. * * @return * - #ER_OK if successful. * - #ER_BUS_BAD_CHILD_PATH if the path given was not a valid path * - #ER_BUS_OBJ_NOT_FOUND if the Child object was not found * - #ER_FAIL any other unexpected error. */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_removechild(alljoyn_proxybusobject proxyObj, const char* path); /** * Query the remote object on the bus to determine the interfaces and * children that exist. Use this information to populate this proxy's * interfaces and children. * * This call causes messages to be send on the bus, therefore it cannot * be called within AllJoyn callbacks (method/signal/reply handlers or * ObjectRegistered callbacks, etc.) * * @param proxyObj The proxy bus object that will query the remote object. * * @return * - #ER_OK if successful * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_introspectremoteobject(alljoyn_proxybusobject proxyObj); /** * Query the remote object on the bus to determine the interfaces and * children that exist. Use this information to populate this object's * interfaces and children. * * This call executes asynchronously. When the introspection response * is received from the actual remote object, this alljoyn_proxybusobject will * be updated and the callback will be called. * * This call exists primarily to allow introspection of remote objects * to be done inside AllJoyn method/signal/reply handlers and ObjectRegistered * callbacks. * * @param proxyObj The proxy bus object that will query the remote object. * @param callback Method on listener that will be called. * @param context User defined context which will be passed as-is to callback. * @return * - #ER_OK if successful. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_introspectremoteobjectasync(alljoyn_proxybusobject proxyObj, alljoyn_proxybusobject_listener_introspectcb_ptr callback, void* context); /** * Get a property from an interface on the remote object. * * @param proxyObj The proxy bus object the property will be read from * @param iface Name of interface to retrieve property from. * @param property The name of the property to get. * @param[out] value Property value. * * @return * - #ER_OK if the property was obtained. * - #ER_BUS_OBJECT_NO_SUCH_INTERFACE if the no such interface on this remote object. * - #ER_BUS_NO_SUCH_PROPERTY if the property does not exist */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_getproperty(alljoyn_proxybusobject proxyObj, const char* iface, const char* property, alljoyn_msgarg value); /** * Make an asynchronous request to get a property from an interface on the remote object. * The property value is passed to the callback function. * * @param proxyObj The proxy bus object the property will be read from * @param iface Name of interface to retrieve property from. * @param property The name of the property to get. * @param callback Function that will be called when the getproperty operation is completed. * @param timeout Timeout specified in milliseconds to wait for a reply. * Recommended default #ALLJOYN_MESSAGE_DEFAULT_TIMEOUT which is 25000 ms. * @param context User defined context which will be passed as-is to callback. * * @return * - #ER_OK if the request to get the property was successfully issued . * - #ER_BUS_OBJECT_NO_SUCH_INTERFACE if the no such interface on this remote object. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_getpropertyasync(alljoyn_proxybusobject proxyObj, const char* iface, const char* property, alljoyn_proxybusobject_listener_getpropertycb_ptr callback, uint32_t timeout, void* context); /** * Get all properties from an interface on the remote object. * * @param proxyObj The proxy bus object the properties will be read from * @param iface Name of interface to retrieve all properties from. * @param[out] values Property values returned as an array of dictionary entries, signature "a{sv}". * * @return * - #ER_OK if the property was obtained. * - #ER_BUS_OBJECT_NO_SUCH_INTERFACE if the no such interface on this remote object. * - #ER_BUS_NO_SUCH_PROPERTY if the property does not exist */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_getallproperties(alljoyn_proxybusobject proxyObj, const char* iface, alljoyn_msgarg values); /** * Make an asynchronous request to get all properties from an interface on the remote object. * * @param proxyObj The proxy bus object the properties will be read from * @param iface Name of interface to retrieve properties from. * @param callback Function that will be called when the getallproperties operation is completed. * @param timeout Timeout specified in milliseconds to wait for a reply * Recommended default #ALLJOYN_MESSAGE_DEFAULT_TIMEOUT which is 25000 ms. * @param context User defined context which will be passed as-is to callback. * * @return * - #ER_OK if the request to get all properties was successfully issued . * - #ER_BUS_OBJECT_NO_SUCH_INTERFACE if the no such interface on this remote object. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_getallpropertiesasync(alljoyn_proxybusobject proxyObj, const char* iface, alljoyn_proxybusobject_listener_getallpropertiescb_ptr callback, uint32_t timeout, void* context); /** * Set a property on an interface on the remote object. * * @param proxyObj The proxy bus object the property will be set on * @param iface Interface that holds the property * @param property The name of the property to set * @param value The value to set * * @return * - #ER_OK if the property was set * - #ER_BUS_OBJECT_NO_SUCH_INTERFACE if the no such interface on this remote object. * - #ER_BUS_NO_SUCH_PROPERTY if the property does not exist */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_setproperty(alljoyn_proxybusobject proxyObj, const char* iface, const char* property, alljoyn_msgarg value); /** * Function to register a handler for property change events. * * @param proxyObj The proxy bus object that will register the property changed * listener * @param iface Remote object's interface on which the property is defined. * @param properties List of names of properties to monitor. * @param numProperties Number of properties to monitor. * @param callback Method on listener that will be called. * @param context User defined context which will be passed as-is to callback. * * @return * - #ER_OK if the handler was registered successfully * - #ER_BUS_OBJECT_NO_SUCH_INTERFACE if the specified interfaces does not * exist on the remote object. * - #ER_BUS_NO_SUCH_PROPERTY if the property does not exist */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_registerpropertieschangedlistener(alljoyn_proxybusobject proxyObj, const char* iface, const char** properties, size_t numProperties, alljoyn_proxybusobject_listener_propertieschanged_ptr callback, void* context); /** * Function to unregister a handler for property change events. * * @param proxyObj The proxy bus object that will register the property changed listener. * @param iface Remote object's interface on which the properties are defined. * @param callback Method on listener that used to be called. * * @return * - #ER_OK if the handler was unregistered successfully * - #ER_BUS_OBJECT_NO_SUCH_INTERFACE if the specified interfaces does not exist on the remote object. */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_unregisterpropertieschangedlistener(alljoyn_proxybusobject proxyObj, const char* iface, alljoyn_proxybusobject_listener_propertieschanged_ptr callback); /** * Make an asynchronous request to set a property on an interface on the remote object. * A callback function reports the success or failure of there operation. * * @param proxyObj The proxy bus object the property will be set o * @param iface Remote object's interface on which the property is defined. * @param property The name of the property to set. * @param value The value to set * @param callback Function that will be called when the setproperty operation is completed. * @param timeout Timeout specified in milliseconds to wait for a reply * Recommended default #ALLJOYN_MESSAGE_DEFAULT_TIMEOUT which is 25000 ms. * @param context User defined context which will be passed as-is to callback. * * @return * - #ER_OK if the request to set the property was successfully issued . * - #ER_BUS_OBJECT_NO_SUCH_INTERFACE if the specified interfaces does not exist on the remote object. * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_setpropertyasync(alljoyn_proxybusobject proxyObj, const char* iface, const char* property, alljoyn_msgarg value, alljoyn_proxybusobject_listener_setpropertycb_ptr callback, uint32_t timeout, void* context); /** * Make a synchronous method call * * @param proxyObj alljoyn_proxybusobject on which to call the method. * @param ifaceName Name of interface. * @param methodName Name of method. * @param args The arguments for the method call (can be NULL) * @param numArgs The number of arguments * @param replyMsg The reply message received for the method call * @param timeout Timeout specified in milliseconds to wait for a reply * @param flags Logical OR of the message flags for this method call. The following flags apply to method calls: * - If #ALLJOYN_MESSAGE_FLAG_ENCRYPTED is set the message is authenticated and the payload if any is encrypted. * - If #ALLJOYN_MESSAGE_FLAG_AUTO_START is set the bus will attempt to start a service if it is not running. * * @return * - #ER_OK if the method call succeeded and the reply message type is #ALLJOYN_MESSAGE_METHOD_RET * - #ER_BUS_REPLY_IS_ERROR_MESSAGE if the reply message type is #ALLJOYN_MESSAGE_ERROR */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_methodcall(alljoyn_proxybusobject proxyObj, const char* ifaceName, const char* methodName, const alljoyn_msgarg args, size_t numArgs, alljoyn_message replyMsg, uint32_t timeout, uint8_t flags); /** * Make a synchronous method call from this object * * @param proxyObj alljoyn_proxybusobject on which to call the method. * @param method The alljoyn_interfacedescription_member specifying the method being invoked. * @param args The arguments for the method call (can be NULL) * @param numArgs The number of arguments * @param replyMsg The reply message received for the method call * @param timeout Timeout specified in milliseconds to wait for a reply. * Recommended default #ALLJOYN_MESSAGE_DEFAULT_TIMEOUT which is 25000 ms. * @param flags Logical OR of the message flags for this method call. The following flags apply to method calls: * - If #ALLJOYN_MESSAGE_FLAG_ENCRYPTED is set the message is authenticated and the payload if any is encrypted. * - If #ALLJOYN_MESSAGE_FLAG_AUTO_START is set the bus will attempt to start a service if it is not running. * Set value to '0' for no flags. * * * @return * - #ER_OK if the method call succeeded and the reply message type is #ALLJOYN_MESSAGE_METHOD_RET * - #ER_BUS_REPLY_IS_ERROR_MESSAGE if the reply message type is #ALLJOYN_MESSAGE_ERROR */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_methodcall_member(alljoyn_proxybusobject proxyObj, const alljoyn_interfacedescription_member method, const alljoyn_msgarg args, size_t numArgs, alljoyn_message replyMsg, uint32_t timeout, uint8_t flags); /** * Make a fire-and-forget method call from this object. The caller will not be able to tell if * the method call was successful or not. This is equivalent to calling MethodCall() with * flags == ALLJOYN_FLAG_NO_REPLY_EXPECTED. Because this call doesn't block it can be made from * within a signal handler. * * @param proxyObj alljoyn_proxybusobject on which to call the method. * @param ifaceName Name of interface. * @param methodName Name of method. * @param args The arguments for the method call (can be NULL) * @param numArgs The number of arguments * @param flags Logical OR of the message flags for this method call. The following flags apply to method calls: * - If #ALLJOYN_MESSAGE_FLAG_ENCRYPTED is set the message is authenticated and the payload if any is encrypted. * - If #ALLJOYN_MESSAGE_FLAG_AUTO_START is set the bus will attempt to start a service if it is not running. * Set value to '0' for no flags. * * @return * - #ER_OK if the method call succeeded */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_methodcall_noreply(alljoyn_proxybusobject proxyObj, const char* ifaceName, const char* methodName, const alljoyn_msgarg args, size_t numArgs, uint8_t flags); /** * Make a fire-and-forget method call from this object. The caller will not be able to tell if * the method call was successful or not. This is equivalent to calling MethodCall() with * flags == ALLJOYN_FLAG_NO_REPLY_EXPECTED. Because this call doesn't block it can be made from * within a signal handler. * * @param proxyObj alljoyn_proxybusobject on which to call the method. * @param method Method being invoked. * @param args The arguments for the method call (can be NULL) * @param numArgs The number of arguments * @param flags Logical OR of the message flags for this method call. The following flags apply to method calls: * - If #ALLJOYN_MESSAGE_FLAG_ENCRYPTED is set the message is authenticated and the payload if any is encrypted. * - If #ALLJOYN_MESSAGE_FLAG_AUTO_START is set the bus will attempt to start a service if it is not running. * Set value to '0' for no flags. * * @return * - #ER_OK if the method call succeeded */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_methodcall_member_noreply(alljoyn_proxybusobject proxyObj, const alljoyn_interfacedescription_member method, const alljoyn_msgarg args, size_t numArgs, uint8_t flags); /** * Make an asynchronous method call from this object * * @param proxyObj alljoyn_proxybusobject on which to call the method * @param ifaceName Name of interface for method. * @param methodName Name of method. * @param replyFunc The function that is called to deliver the reply * @param args The arguments for the method call (can be NULL) * @param numArgs The number of arguments (can be 0) * @param context User-defined context that will be returned to the reply handler * Recommended default NULL. * @param timeout Timeout specified in milliseconds to wait for a reply * Recommended default #ALLJOYN_MESSAGE_DEFAULT_TIMEOUT which is 25000 ms * @param flags Logical OR of the message flags for this method call. The following flags apply to method calls: * - If #ALLJOYN_MESSAGE_FLAG_ENCRYPTED is set the message is authenticated and the payload if any is encrypted. * - If #ALLJOYN_MESSAGE_FLAG_AUTO_START is set the bus will attempt to start a service if it is not running. * Set value to '0' for no flags. * @return * - ER_OK if successful * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_methodcallasync(alljoyn_proxybusobject proxyObj, const char* ifaceName, const char* methodName, alljoyn_messagereceiver_replyhandler_ptr replyFunc, const alljoyn_msgarg args, size_t numArgs, void* context, uint32_t timeout, uint8_t flags); /** * Make an asynchronous method call from this object * * @param proxyObj alljoyn_proxybusobject on which to call the method * @param method Method being invoked. * @param replyFunc The function that is called to deliver the reply * @param args The arguments for the method call (can be NULL) * @param numArgs The number of arguments (can be 0) * @param context User-defined context that will be returned to the reply handler * Recommended default NULL. * @param timeout Timeout specified in milliseconds to wait for a reply * Recommended default #ALLJOYN_MESSAGE_DEFAULT_TIMEOUT which is 25000 ms * @param flags Logical OR of the message flags for this method call. The following flags apply to method calls: * - If #ALLJOYN_MESSAGE_FLAG_ENCRYPTED is set the message is authenticated and the payload if any is encrypted. * - If #ALLJOYN_MESSAGE_FLAG_AUTO_START is set the bus will attempt to start a service if it is not running. * Set value to '0' for no flags. * @return * - ER_OK if successful * - An error status otherwise */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_methodcallasync_member(alljoyn_proxybusobject proxyObj, const alljoyn_interfacedescription_member method, alljoyn_messagereceiver_replyhandler_ptr replyFunc, const alljoyn_msgarg args, size_t numArgs, void* context, uint32_t timeout, uint8_t flags); /** * Initialize this proxy object from an XML string. Calling this function does several things: * * -# Create and register any new InterfaceDescription(s) that are mentioned in the XML. * (Interfaces that are already registered with the bus are left "as-is".) * -# Add all the interfaces mentioned in the introspection data to this alljoyn_proxybusobject. * -# Recursively create any child alljoyn_proxybusobject(s) and create/add their associated @n * interfaces as mentioned in the XML. Then add the descendant object(s) to the appropriate * descendant of this alljoyn_proxybusobject (in the children collection). If the named * child object already exists as a child of the appropriate alljoyn_proxybusobject, then it is * updated to include any new interfaces or children mentioned in the XML. * * Note that when this function fails during parsing, the return code will be set accordingly. * However, any interfaces which were successfully parsed prior to the failure * may be registered with the bus. Similarly, any objects that were successfully created * before the failure will exist in this object's set of children. * * @param proxyObj alljoyn_proxybusobject which will be initialized from the XML string * @param xml An XML string in DBus introspection format. * @param identifier An optional identifying string to include in error logging messages. * * @return * - #ER_OK if parsing is completely successful. * - An error status otherwise. */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_parsexml(alljoyn_proxybusobject proxyObj, const char* xml, const char* identifier); /** * Explicitly secure the connection to the remote peer for this proxy object. Peer-to-peer * connections can only be secured if EnablePeerSecurity() was previously called on the bus * attachment for this proxy object. If the peer-to-peer connection is already secure this * function does nothing. Note that peer-to-peer connections are automatically secured when a * method call or signal requiring encryption is sent or received. * * This call causes messages to be sent on the bus, therefore it cannot be called within AllJoyn * callbacks (method/signal/reply handlers or ObjectRegistered callbacks, etc.) * * @param proxyObj alljoyn_proxybusobject to explicitly set up a secure a connection * @param forceAuth If true, forces an re-authentication even if the peer connection is already * authenticated. * Recommended default QCC_FALSE * * @return * - #ER_OK if the connection was secured or an error status indicating that the * connection could not be secured. * - #ER_BUS_NO_AUTHENTICATION_MECHANISM if alljoyn_busattachment_enablepeersecurity() * has not been called. * - #ER_AUTH_FAIL if the attempt(s) to authenticate the peer failed. * - Other error status codes indicating a failure. */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_secureconnection(alljoyn_proxybusobject proxyObj, QCC_BOOL forceAuth); /** * Asynchronously secure the connection to the remote peer for this proxy object. * Peer-to-peer connections can only be secured if alljoyn_busattachment_enablepeersecurity() * was previously called on the bus attachment for this proxy object. If the peer-to-peer * connection is already secure this function does nothing. Note that peer-to-peer * connections are automatically secured when a method call or signal requiring * encryption is sent or received. * * Notification of success or failure is via the AuthListener passed to * alljoyn_busattachment_enablepeersecurity(). * * @param proxyObj alljoyn_proxybusobject to explicitly set up a secure a connection * @param forceAuth If true, forces an re-authentication even if the peer connection is already * authenticated. * Recommended default QCC_FALSE * * @return * - #ER_OK if securing could begin. * - #ER_BUS_NO_AUTHENTICATION_MECHANISM if alljoyn_busattachment_enablepeersecurity() has not been called. * - Other error status codes indicating a failure. */ extern AJ_API QStatus AJ_CALL alljoyn_proxybusobject_secureconnectionasync(alljoyn_proxybusobject proxyObj, QCC_BOOL forceAuth); /** * Returns a pointer to an interface description. Returns NULL if the object does not implement * the requested interface. * * @param proxyObj The proxy bus object to obtain an interface description from. * @param iface The name of interface to get. * * @return * - A pointer to the requested interface description. * - NULL if requested interface is not implemented or not found */ extern AJ_API const alljoyn_interfacedescription AJ_CALL alljoyn_proxybusobject_getinterface(alljoyn_proxybusobject proxyObj, const char* iface); /** * Returns the interfaces implemented by this object. Note that all proxy bus objects * automatically inherit the "org.freedesktop.DBus.Peer" which provides the built-in "ping" * method, so this method always returns at least that one interface. * * @param proxyObj The proxy bus object to obtain an interface descriptions from. * @param ifaces A pointer to an InterfaceDescription array to receive the interfaces. Can be NULL in * which case no interfaces are returned and the return value gives the number * of interfaces available. * @param numIfaces The size of the InterfaceDescription array. If this value is smaller than the total * number of interfaces only numIfaces will be returned. * (DEFAULT) if numInterfaces is 0 then no interfaces will be returned. * * @return The number of interfaces returned or the total number of interfaces if ifaces is NULL. */ extern AJ_API size_t AJ_CALL alljoyn_proxybusobject_getinterfaces(alljoyn_proxybusobject proxyObj, const alljoyn_interfacedescription* ifaces, size_t numIfaces); /** * Return the absolute object path for the remote object. * * @param proxyObj the proxy bus object to read the object path from. * * @return Object path */ extern AJ_API const char* AJ_CALL alljoyn_proxybusobject_getpath(alljoyn_proxybusobject proxyObj); /** * Return the remote service name for this object. * * @param proxyObj the proxy bus object to read the service name (Bus Name) path from. * * @return Service name (typically a well-known service name but may be a unique name) */ extern AJ_API const char* AJ_CALL alljoyn_proxybusobject_getservicename(alljoyn_proxybusobject proxyObj); /** * Return the remote unique name for this object. * * @param proxyObj the proxy bus object to read the unique name (Bus Name) path from. * * @return Unique name */ extern AJ_API const char* AJ_CALL alljoyn_proxybusobject_getuniquename(alljoyn_proxybusobject proxyObj); /** * Return the session Id for this object. * * @param proxyObj the proxy bus object we wish to obtain the session ID from. * @return Session Id */ extern AJ_API alljoyn_sessionid AJ_CALL alljoyn_proxybusobject_getsessionid(alljoyn_proxybusobject proxyObj); /** * Tests if this object implements the requested interface. * * @param proxyObj the proxy bus object we wish check for the interface * @param iface The interface to check * * @return true if the object implements the requested interface */ extern AJ_API QCC_BOOL AJ_CALL alljoyn_proxybusobject_implementsinterface(alljoyn_proxybusobject proxyObj, const char* iface); /** * create a copy of a proxybusobject. This will create a new alljoyn_proxybusobject and * must be cleaned up using alljoyn_proxybusobject_destroy. * * @param source the alljoyn_proxybusobject to be copied * * @return copy of the alljoyn_proxybusobject argument is returned */ extern AJ_API alljoyn_proxybusobject AJ_CALL alljoyn_proxybusobject_copy(const alljoyn_proxybusobject source); /** * Indicates if this is a valid (usable) proxy bus object. * * @param proxyObj The alljoyn_proxybusobject to be checked for usability * * @return true if a valid proxy bus object, false otherwise. */ extern AJ_API QCC_BOOL AJ_CALL alljoyn_proxybusobject_isvalid(alljoyn_proxybusobject proxyObj); /** * Indicates if the remote object for this proxy bus object is secure. * * @param proxyObj The alljoyn_proxybusobject to be checked for usability * * @return true if the object is secure */ extern AJ_API QCC_BOOL AJ_CALL alljoyn_proxybusobject_issecure(alljoyn_proxybusobject proxyObj); /** * Enable property caching for this proxy bus object. * * @param proxyObj The alljoyn_proxybusobject for which caching must be enabled */ extern AJ_API void AJ_CALL alljoyn_proxybusobject_enablepropertycaching(alljoyn_proxybusobject proxyObj); #ifdef __cplusplus } /* extern "C" */ #endif #endif