node-alljoyn

/* * Copyright (c) 2011-2015, 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. */ /** * \file * * \name AllJoyn™ JavaScript API Reference Manual * \version 14.12.00b * * Type coercion between DBus and JavaScript types is done according to the following table. * <table> * <tr><th>IDL type</th><th>DBus type</th><th>Signature</th><th>JavaScript * type</th></tr> * <tr><td>octet</td><td>BYTE</td><td>'y'</td><td>Number</td></tr> * <tr><td>boolean</td><td>BOOLEAN</td><td>'b'</td><td>Boolean</td></tr> * <tr><td>short</td><td>INT16</td><td>'n'</td><td>Number</td></tr> * <tr><td>unsigned short</td><td>UINT16</td><td>'q'</td><td>Number</td></tr> * <tr><td>long</td><td>INT32</td><td>'i'</td><td>Number</td></tr> * <tr><td>unsigned long</td><td>UINT32</td><td>'u'</td><td>Number</td></tr> * <tr><td>long long</td><td>INT64</td><td>'x'</td><td>The DBus value is coerced into a decimal * string. Use parseInt to convert the argument to a number if loss of precision is not a * concern.</td></tr> * <tr><td>unsigned long long</td><td>UINT64</td><td>'t'</td><td>The DBus value is coerced into a * decimal string. Use parseInt to convert the argument to a number if loss of precision * is not a concern.</td></tr> * <tr><td>double</td><td>DOUBLE</td><td>'d'</td><td>Number</td></tr> * <tr><td>DOMString</td><td>STRING</td><td>'s'</td><td>String</td></tr> * <tr><td>DOMString</td><td>OBJECT_PATH</td><td>'o'</td><td>String</td></tr> * <tr><td>DOMString</td><td>SIGNATURE</td><td>'g'</td><td>String</td></tr> * <tr><td>sequence<T></td><td>ARRAY</td><td>'a'</td><td>When the DBus value is an array of * DICT_ENTRY, the argument will be an Object where each property is the DICT_ENTRY key and each * value is the DICT_ENTRY value. Otherwise the argument will be an Array.</td></tr> * <tr><td>sequence<any></td><td>STRUCT</td><td>'r', '(', ')'</td><td>Array</td></tr> * <tr><td>any</td><td>VARIANT</td><td>'v'</td><td>DBus VARIANT types remove the VARIANT wrapper. * For example, a VARIANT of the string "value" will be "value". Nested VARIANTs will * remove only one VARIANT wrapper. For example, a VARIANT of a VARIANT of a string will be the * Object { "s": "value" }.</td></tr> * </table> * * Debug output of the plugin can be configured dynamically by setting the debug attribute of the * object element containing the plugin. The syntax of the attribute value is the same as * BusAttachment.setDaemonDebug, e.g. debug="ALLJOYN_JS=15". The destination for debug * output depends on the platform: Windows is OutputDebugString, and for all * others it is stdout. */ /** \brief SessionId uniquely identifies an AllJoyn session instance. */ typedef unsigned long SessionId; /** * \brief SessionPort identifies a per-BusAttachment receiver for incoming JoinSession * requests. * * SessionPort values are bound to a BusAttachment when the attachment calls * BindSessionPort. * * NOTE: Valid SessionPort values range from 1 to 0xFFFF. */ typedef unsigned short SessionPort; /** \brief Bitmask of all transport types */ typedef unsigned short TransportMask; /** \brief Status code value */ typedef unsigned short Status; /** * \brief AllJoyn-specific error codes. * * Note that NPAPI does not support raising custom exceptions, and the browsers behave * differently. To workaround this, the plugin provides the name, message, and code * fields of the most recently raised exception on the exception interface object. */ exception BusError { ##STATUS## /** * \brief The error name. * * The default value is "BusError". */ DOMString name; /** * \brief The error message. * * The default value is the empty string. */ DOMString message; /** * \brief The error code. */ Status code; }; /** * \brief Accept or reject an incoming JoinSession request. The session does not exist * until this after this operation returns. * * This callback is only used by session creators. Therefore it is only called on listeners * passed to BusAttachment.bindSessionPort. * * \param port session port that was joined * \param joiner unique name of potential joiner * \param opts session options requested by the joiner * \return true if JoinSession request is accepted. false if rejected. */ callback AcceptSessionJoinerListener = boolean (SessionPort port, DOMString joiner, SessionOpts opts); /** * \brief Interface to allow authentication mechanisms to interact with the user or * application. */ [NoInterfaceObject] callback interface AuthListener { /** * \brief The authentication mechanism requests user credentials. * * If the user name is not an empty string the request is for credentials for that * specific user. A count allows the listener to decide whether to allow or reject * multiple authentication attempts to the same peer. * * \param authMechanism the name of the authentication mechanism issuing the request * \param peerName the name of the remote peer being authenticated. On the * initiating side this will be a well-known-name for the remote * peer. On the accepting side this will be the unique bus name for * the remote peer. * \param authCount count (starting at 1) of the number of authentication request * attempts made * \param userName the user name for the credentials being requested * \param credMask a bit mask identifying the credentials being requested. The * application may return none, some or all of the requested * credentials. * \param credentials the credentials returned * * \return the caller should return true if the request is being accepted or false * if the requests is being rejected. If the request is rejected the * authentication is complete. */ boolean onRequest(DOMString authMechanism, DOMString peerName, unsigned short authCount, DOMString userName, unsigned short credMask, Credentials credentials); /** * \brief The authentication mechanism requests verification of credentials from a * remote peer. * * This operation is mandatory for the ALLJOYN_RSA_KEYX auth mechanism, optional for others. * * \param authMechanism the name of the authentication mechanism issuing the request * \param peerName the name of the remote peer being authenticated. On the * initiating side this will be a well-known-name for the remote * peer. On the accepting side this will be the unique bus name for * the remote peer. * \param credentials the credentials to be verified * * \return the listener should return true if the credentials are acceptable or * false if the credentials are being rejected. */ boolean onVerify(DOMString authMechanism, DOMString peerName, Credentials credentials); /** * \brief Optional operation that if implemented allows an application to monitor * security violations. * * This operation is called when an attempt to decrypt an encrypted messages failed * or when an unencrypted message was received on an interface that requires * encryption. The message contains only header information. * * \param status a status code indicating the type of security violation * \param context the message that cause the security violation */ void onSecurityViolation(Status status, Message context); /** * \brief Reports successful or unsuccessful completion of authentication. * * \param authMechanism the name of the authentication mechanism that was used or an * empty string if the authentication failed * \param peerName the name of the remote peer being authenticated. On the * initiating side this will be a well-known-name for the remote * peer. On the accepting side this will be the unique bus name for * the remote peer. * \param success true if the authentication was successful, otherwise false */ void onComplete(DOMString authMechanism, DOMString peerName, boolean success); }; [/** * \brief Constructs a new BusAttachment. * * \param allowRemoteMessages true if this attachment is allowed to receive messages * from remote devices. Defaults to false. */Constructor(optional boolean allowRemoteMessages)] /** * \brief BusAttachment is the top-level object responsible for connecting to and optionally * managing a message bus. */ interface BusAttachment { /** * \brief Value for requestName flags bit corresponding to allowing another bus * attachment to take ownership of this name. */ const unsigned long DBUS_NAME_FLAG_ALLOW_REPLACEMENT = 0x01; /** * \brief Value for requestName flags bit corresponding to a request to take * ownership of the name in question if it is already taken. */ const unsigned long DBUS_NAME_FLAG_REPLACE_EXISTING = 0x02; /** * \brief Value for requestName flags bit corresponding to a request to fail if the * name in question cannot be immediately obtained. */ const unsigned long DBUS_NAME_FLAG_DO_NOT_QUEUE = 0x04; /** * \brief Invalid SessionPort value used to indicate that bindSessionPort should * choose any available port. */ const unsigned short SESSION_PORT_ANY = 0; /** * \brief The GUID of this BusAttachment. * * The returned value may be appended to an advertised well-known name in order to * guarantee that the resulting name is globally unique. * * Read-only. */ readonly attribute DOMString globalGUIDString; /** * \brief The unique name of this BusAttachment. * * Read-only. * * null if not connected. */ readonly attribute DOMString uniqueName; /** * \brief Registers a locally located DBus object. * * Throws BusError BUS_BAD_OBJ_PATH if the object path is bad. * * \param objectPath the absolute object path of the DBus object * \param busObject the DBus object implementation * \param cb callback function that should be run once the BusObject has * been registered */ setter void registerBusObject(DOMString objectPath, BusObject busObject, statusCallback cb); /** * \brief Unregisters a locally located DBus object. * * \param objectPath the absolute object path of the DBus object * \param cb callback function that should be run once the BusObject has * been unregistered. */ deleter void unregisterBusObject(DOMString objectPath, statusCallback cb); /** * \brief create a new BusAttachment. * * create must be called before any other BusAttachment methods. This call * is responsible for making sure proper creation a native BusAttachment. * * \param allowRemoteMessages True if this attachment is allowed to receive messages from remote devices. * \param cb callback function called once the native BusAttachment has been created. */ void create(boolean allowRemoteMessages, statusCallback cb); /** * \brief add the interface specified by the interfaceDescription to the BusAttachment * * The interfaceDescription must be a full interface specification. The interface is * created and activated on the BusAttachment. * * \param interfaceDescription the specification for the interface being created. * \param cb the function called once the createInterface method has completed. */ void createInterface(InterfaceDescription interfaceDescription, statusCallback cb); /** * Initialize one more interface descriptions from an XML string in DBus introspection format. * The root tag of the XML can be a \<node\> or a stand alone \<interface\> tag. To initialize more * than one interface the interfaces need to be nested in a \<node\> tag. * * Note that when this method 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. * * ]param xml An XML string in DBus introspection format. * \param cb callback function that is run after creating the interfaces from * xml. Callback will specify OK if parsing is completely successful. * An error status otherwise. */ void createInterfacesFromXML(DOMString xml, statusCallback cb); /** * \brief Connects to a remote bus address. * * \param connectSpec an optional transport connection spec string of the form * "\<transport\>:\<param1\>=\<value1\>,\<param2\>=\<value2\>...[;]". * The default value is platform-specific. * \param cb callback function that is called once connect has completed. */ void connect(optional DOMString connectSpec, statusCallback cb); /** * \brief Disconnects from a remote bus address connection. * * \param cb Callback function will specify BUS_NOT_STARTED if the bus is not started. * BUS_NOT_CONNECTED if the BusAttachment is not connected to the bus. * Other error status codes indicating a failure. */ void disconnect(statusCallback cb); /** * \brief Explicitly release the reference to the BusAttachment object * * Explicitly releasing the reference to the BusAttachment object makes it * so the JavaScript garbage-collector can free up the reference to the native * BusAttachment. * destroy should be called when the BusAttachment is no longer needed. * * \param cb function that should be run once destroy method call has completed */ void destroy(statusCallback cb); /** * \brief Registers a signal handler. * * Signals are forwarded to the signal handler if the sender, interface, member and path * qualifiers are all met. * * If multiple identical signal handlers are registered with the same parameters the * duplicate instances are discarded. They do not need to be removed with the * unregisterSignalHandler operation. * * \param signalListener the function called when the signal is received * \param signalName the interface and member of the signal of the form * "org.sample.Foo.Echoed" where "org.sample.Foo" is * the interface and "Echoed" is the member * \param sourcePath the optional object path of the emitter of the signal * \param cb status callback that will contain: * BUS_NO_SUCH_INTERFACE if the interface part of signalName does not exist. * BUS_NO_SUCH_MEMBER if the member part of signalName does not exist. * Other error status codes indicating a failure. */ void registerSignalHandler(MessageListener signalListener, DOMString signalName, optional DOMString sourcePath, statusCallback cb); /** * \brief Unregisters a signal handler. * * This must be called with the identical parameters supplied to registerSignalHandler. * * \param signalListener the function called when the signal is received * \param signalName the interface and member of the signal of the form * "org.sample.Foo.Echoed" where "org.sample.Foo" is * the interface and "Echoed" is the member * \param sourcePath the optional object path of the emitter of the signal * \param cb statusCallback with contain: * OK if request was successful * BUS_NOT_CONNECTED if a connection has not been made with a local bus. * other error status codes indicating a failure. */ void unregisterSignalHandler(MessageListener signalListener, DOMString signalName, optional DOMString sourcePath, statusCallback cb); /** * \brief Registers an object that will receive bus event notifications. * * \param listener the object that will receive bus event notifications * \param cb callback function that is run after registerBusListener has completed */ void registerBusListener(BusListener listener, statusCallback cb); /** * \brief Unregisters an object that was previously registered with addBusListener. * * \param listener the object instance to unregister as a listener * \param cb indicates function that will be run once unregisterBusListener * method has completed. */ void unregisterBusListener(BusListener listener, statusCallback cb); /** * \brief Requests a well-known name. * * This operation is a shortcut/helper that issues an org.freedesktop.DBus.RequestName method * call to the local daemon and interprets the response. * * \param requestedName well-known name being requested * \param flags bitmask of DBUS_NAME_FLAG_* constants. Defaults to 0. * \param cb the statusCallback will contain: * BUS_NOT_CONNECTED if a connection has not been made with a local bus. * Other error status codes indicating a failure. */ void requestName(DOMString requestedName, optional unsigned long flags, statusCallback cb); /** * \brief Releases a previously requeted well-known name. * * This operation is a shortcut/helper that issues an org.freedesktop.DBus.ReleaseName method * call to the local daemon and interprets the response. * * \param name well-known name being released * \param cb callback function that will contain the following status: * BUS_NOT_CONNECTED if a connection has not been made with a local bus. * Other error status codes indicating a failure. */ void releaseName(DOMString name, statusCallback cb); /** * \brief Adds a DBus match rule. * * This operation is a shortcut/helper that issues an org.freedesktop.DBus.AddMatch method call * to the local daemon. * * \param rule match rule to be added (see DBus specification for format of this string) * \param cb callback function to run after addMatch has completed. callback will contain * status BUS_NOT_CONNECTED if a connection has not been made with a local bus. * Other error status codes indicating a failure. */ void addMatch(DOMString rule, statusCallback cb); /** * \brief Removes a DBus match rule. * * This operation is a shortcut/helper that issues an org.freedesktop.DBus.RemoveMatch * method call to the local daemon. * * \param rule match rule to be removed (see DBus specification for format of this * string) * \param cb The statusCallback will contain: * BUS_NOT_CONNECTED if a connection has not been made with a local bus. * Other error status codes indicating a failure. */ void removeMatch(DOMString rule, statusCallback cb); /** * \brief Advertises the existence of a well-known name to other (possibly disconnected) * AllJoyn daemons. * * This operation is a shortcut/helper that issues an org.alljoyn.Bus.AdvertisedName method * call to the local daemon and interprets the response. * * \param name the well-known name to advertise. (Must be owned by the caller via RequestName) * \param transports set of transports to use for sending advertisment * \param cb callback function to run after name is advertised. Callback will * contain status BUS_NOT_CONNECTED if a connection has not been * made with a local bus. * Other error status codes indicating a failure */ void advertiseName(DOMString name, TransportMask transports, statusCallback cb); /** * \brief Stops advertising the existence of a well-known name to other AllJoyn daemons. * * This operation is a shortcut/helper that issues an org.alljoyn.Bus.CancelAdvertiseName * method call to the local daemon and interprets the response. * * \param name a well-known name that was previously advertised via AdvertiseName * \param transports set of transports whose name advertisment will be cancelled * \param cb callback function that is run after cancelAdvertiseName * callback returns * BUS_NOT_CONNECTED if a connection has not been made with a local bus * Other error status codes indicating a failure */ void cancelAdvertiseName(DOMString name, TransportMask transports, statusCallback cb); /** * \brief Registers interest in a well-known name prefix for the purpose of discovery. * * This operation is a shortcut/helper that issues an org.alljoyn.Bus.FindAdvertisedName method * call to the local daemon and interprets the response. * * \param namePrefix well-known name prefix that application is interested in receiving * BusListener onFoundAdvertisedName notifications about * \param cb function called after the findAdvertisedName method has completed * callback returns BUS_NOT_CONNECTED if a connection has not been made with a local bus * or Other error status codes indicating a failure */ void findAdvertisedName(DOMString namePrefix, statusCallback cb); /** * \brief Retrieve an existing activated InterfaceDescription. * * \param name interface name * \param cb callback containing the specified interfaceDescritption. */ void getInterface(DOMString name, interfaceDescriptionCallback cb); /** * Returns the existing activated InterfaceDescriptions. * * \param cb callback containing the specified unterfaceDescritptions */ void getInterfaces(interfaceDescriptionsCallback cb); /** * \brief Cancels interest in a well-known name prefix that was previously registered with * FindAdvertisedName. * * This operation is a shortcut/helper that issues an org.alljoyn.Bus.CancelFindAdvertisedName * method call to the local daemon and interprets the response. * * \param namePrefix well-known name prefix that application is no longer interested in * receiving BusListener onFoundAdvertisedName notifications about * \param cb callback function run after a cancelFindAdvertisedName has completed * Callback will specify BUS_NOT_CONNECTED if a connection has not been made * with a local bus. Other error status codes indicating a failure */ void cancelFindAdvertisedName(DOMString namePrefix, statusCallback cb); /** * \brief Makes a SessionPort available for external BusAttachments to join. * * Each BusAttachment binds its own set of SessionPorts. Session joiners use the bound * session port along with the name of the attachement to create a persistent logical * connection (called a Session) with the original BusAttachment. * * SessionPort and bus name form a unique identifier that BusAttachments use when joining * a session. * * SessionPort values can be pre-arranged between AllJoyn services and their clients * (well-known SessionPorts). * * Once a session is joined using one of the service's well-known SessionPorts, the service * may bind additional SessionPorts (dyanamically) and share these SessionPorts with the * joiner over the original session. The joiner can then create additional sessions with the * service by calling JoinSession with these dynamic SessionPort ids. * * The parameters are supplied as a named-parameter object literal. * <dl> * <dt>port</dt> * <dd>SessionPort value to bind. The default value is SESSION_PORT_ANY to allow * this operation to choose an available port. On successful return, this value will * be the chosen port.</dd> * <dt>traffic</dt> * <dd>TrafficType. The default value is TRAFFIC_MESSAGES.</dd> * <dt>isMultipoint</dt> * <dd>boolean indicating if session is multi-point capable. The default value is * false.</dd> * <dt>proximity</dt> * <dd>Proximity. The default value is PROXIMITY_ANY.</dd> * <dt>transports</dt> * <dd>TransportMask of the allowed transports. The default value is * TRANSPORT_ANY.</dd> * <dt>onAccept</dt> * <dd>an <a href="#::ajn::AcceptSessionJoinerListener">AcceptSessionJoinerListener</a> to * accept or reject an incoming JoinSession request. The session does not exist until this * after this function returns.</dd> * <dt>onJoined</dt> * <dd>a <a href="#::ajn::SessionJoinedListener">SessionJoinedListener</a> called by the bus * when a session has been successfully joined</dd> * <dt>onLost</dt> * <dd>a <a href="#::ajn::SessionLostListener">SessionLostListener</a> called by the bus * when an existing session becomes disconnected</dd> * <dt>onMemberAdded</dt> * <dd>a <a href="#::ajn::SessionMemberAddedListener">SessionMemberAddedListener</a> called * by the bus when a member of a multipoint session is added</dd> * <dt>onMemberRemoved</dt> * <dd>a <a href="#::ajn::SessionMemberRemovedListener">SessionMemberRemovedListener</a> called * by the bus when a member of a multipoint session is removed</dd> * </dl> * * \param parameters see above * \param cb callback function run after bindSessionPort has completed. * BUS_NOT_CONNECTED if a connection has not been made with a local bus. */ void bindSessionPort(object parameters, sessionPortCallBack cb); /** * \brief Cancels an existing port binding. * * \param port existing session port to be un-bound * \param cb The sessionCallback contains: * BUS_NOT_CONNECTED if a connection has not been made with a local bus. * Other error status codes indicating a failure. */ void unbindSessionPort(SessionPort port, sessionCallback cb); /** * \brief Sets the session listener for an existing session ID. * * Calling this operation will override the listener set by a previous call to * setSessionListener or any listener specified in JoinSession. * * The listener is supplied as a named-parameter object literal. * <dl> * <dt>onLost</dt> * <dd>a <a href="#::ajn::SessionLostListener">SessionLostListener</a> called by the bus * when an existing session becomes disconnected</dd> * <dt>onMemberAdded</dt> * <dd>a <a href="#::ajn::SessionMemberAddedListener">SessionMemberAddedListener</a> called * by the bus when a member of a multipoint session is added</dd> * <dt>onMemberRemoved</dt> * <dd>a <a href="#::ajn::SessionMemberRemovedListener">SessionMemberRemovedListener</a> called * by the bus when a member of a multipoint session is removed</dd> * </dl> * * \param id the session id of an existing session * \param listener the listener to associate with the session; see above. May be * null to clear the previous listener. * \param cb callback contains OK if call to setSessionListener was successfull. * */ void setSessionListener(SessionId id, object listener, statusCallback cb); /** * \brief Joins a session. * * This operation is a shortcut/helper that issues an org.alljoyn.Bus.JoinSession method call * to the local daemon and interprets the response. * * The parameters are supplied as a named-parameter object literal. * <dl> * <dt>host</dt> * <dd>mandatory bus name of the attachment that is hosting the the session to be joined</dd> * <dt>port</dt> * <dd>mandatory SessionPort of host to be joined</dd> * <dt>traffic</dt> * <dd>TrafficType. The default value is TRAFFIC_MESSAGES.</dd> * <dt>isMultipoint</dt> * <dd>boolean indicating if session is multi-point capable. The default value is * false.</dd> * <dt>proximity</dt> * <dd>Proximity. The default value is PROXIMITY_ANY.</dd> * <dt>transports</dt> * <dd>TransportMask of the allowed transports. The default value is * TRANSPORT_ANY.</dd> * <dt>onLost</dt> * <dd>a <a href="#::ajn::SessionLostListener">SessionLostListener</a> called by the bus * when an existing session becomes disconnected</dd> * <dt>onMemberAdded</dt> * <dd>a <a href="#::ajn::SessionMemberAddedListener">SessionMemberAddedListener</a> called * by the bus when a member of a multipoint session is added</dd> * <dt>onMemberRemoved</dt> * <dd>a <a href="#::ajn::SessionMemberRemovedListener">SessionMemberRemovedListener</a> called * by the bus when a member of a multipoint session is removed</dd> * </dl> * * \param parameters see above * \param cb function run after joinSession method call has completed */ void joinSession(object parameters, statusCallback cb); /** * \brief Leaves an existing session. * * This operation is a shortcut/helper that issues an org.alljoyn.Bus.LeaveSession method call * to the local daemon and interprets the response. * * \param id session id * \param cb funtion to run after leaveSession method call has completed * * \return BUS_NOT_CONNECTED if a connection has not been made with a local bus. * Other error status codes indicating a failure. */ void leaveSession(SessionId id, statusCallback cb); /** * \brief Gets the file descriptor for a raw (non-message based) session. * * \param id ID of an existing streaming session * \param cb callback that will contain the socket file descriptor for session */ void getSessionFd(SessionId id, socketFdCallback cb); /** * \brief Set the link timeout for a session. * * Link timeout is the maximum number of seconds that an unresponsive * daemon-to-daemon connection will be monitored before declaring the session lost * (via the SessionLostListener onLost callback). Link timeout defaults to 0 which * indicates that AllJoyn link monitoring is disabled. * * Each transport type defines a lower bound on link timeout to avoid defeating * transport specific power management algorithms. * * \param id ID of session whose link timeout will be modified * \param linkTimeout max number of seconds that a link can be unresponsive before * being declared lost. 0 indicates that AllJoyn link monitoring * will be disabled. * \param cb callback that indicates the resulting (possibly upward) adjusted * linkTimeout value that acceptable to the underlying transport */ void setLinkTimeout(SessionId id, unsigned long linkTimeout, linkTimeoutCallback cb); /** * \brief Determines whether a given well-known name exists on the bus. * * This operation is a shortcut/helper that issues an org.freedesktop.DBus.NameHasOwner method * call to the daemon and interprets the response. * * \param name The well known name that the caller is inquiring about * \param cb callback that indicates whether name exists on the bus */ void nameHasOwner(DOMString name, hasOwnerCallback cb); /** * \brief Sets the debug level of the local AllJoyn daemon if that daemon was built in debug * mode. * * The debug level can be set for individual subsystems or for "ALL" subsystems. Common * subsystems are "ALLJOYN" for core AllJoyn code, "ALLJOYN_OBJ" for the sessions management * code and "ALLJOYN_NS" for the TCP name services. Debug levels for specific subsystems * override the setting for "ALL" subsystems. For example if "ALL" is set to 7, but * "ALLJOYN_OBJ" is set to 1, then detailed debug output will be generated for all * subsystems except for "ALLJOYN_OBJ" which will only generate high level debug output. * "ALL" defaults to 0 which is off, or no debug output. * * The debug output levels are actually a bit field that controls what output is generated. * Those bit fields are described below: * <dl> * <dt>0x1</dt><dd>High level debug prints (these debug printfs are not common)</dd> * <dt>0x2</dt><dd>Normal debug prints (these debug printfs are common)</dd> * <dt>0x4</dt><dd>Function call tracing (these debug printfs are used sporadically)</dd> * <dt>0x8</dt><dd>Data dump (really only used in the "SOCKET" module - can generate a * lot of output)</dd> * </dl> * * Typically, when enabling debug for a subsystem, the level would be set to 7 which enables * High level debug, normal debug, and function call tracing. Setting the level 0, forces * debug output to be off for the specified subsystem. * * \param _module name of the module to generate debug output * \param level debug level to set for the module * \param cb the statusCallback will contain: * BUS_NO_SUCH_OBJECT if daemon was not built in debug mode. */ void setDaemonDebug(DOMString _module, unsigned long level, statusCallback cb); /** * \brief Enables peer-to-peer security. * * This operation must be called by applications that want to use authentication and * encryption. * * \param authMechanisms the authentication mechanism(s) to use for peer-to-peer * authentication * \param listener an optional listener that receives password and other * authentication related requests * \param cb callback function that is run once the call to enablePeerSecurity has completed * callback specifies status OK if peer security was enabled */ void enablePeerSecurity(DOMString authMechanisms, optional AuthListener listener, statusCallback cb); /** * \brief Reloads the key store for this bus attachment. * * This function would normally only be called in the case where a single key store * is shared between multiple bus attachments, possibly by different * applications. It is up to the applications to coordinate how and when the shared * key store is modified. * * \param cb statusCallback will contain: * OK if the key store was succesfully reloaded. * An error status indicating that the key store reload failed. */ void reloadKeyStore(statusCallback cb); /** * \brief Clears all stored keys from the key store. * * All store keys and authentication information is deleted and cannot be * recovered. Any passwords or other credentials will need to be reentered when * establishing secure peer connections. * * \param cb callback function called after clearKeyStore has completed. */ void clearKeyStore(statusCallback cb); /** * \brief Clear the keys associated with a specific peer identified by its GUID. * * \param guid the guid of a remote authenticated peer * \param cb callback function that gets called after clearKeys have completed * callback will return OK if the key was cleared. * UNKNOWN_GUID if there is no peer with the specified GUID. * Other error status codes indicating a failure. */ void clearKeys(DOMString guid, statusCallback cb); /** * \brief Set the expiration time on keys associated with a specific remote peer as * identified by its peer GUID. * * The peer GUID associated with a bus name can be obtained by calling * getPeerGUID. If the timeout is 0 this is equivalent to calling clearKeys. * * \param guid the GUID of a remote authenticated peer * \param timeout the time in seconds relative to the current time to expire the * keys * \param cb the statusCallback will contain: * OK if the expiration time was successfully set. * UNKNOWN_GUID if there is no authenticated peer with the specified GUID. * Other error status codes indicating a failure. */ void setKeyExpiration(DOMString guid, unsigned long timeout, statusCallback cb); /** *\brief Get the expiration time on keys associated with a specific authenticated * remote peer as identified by its peer GUID. * * The peer GUID associated with a bus name can be obtained by calling * getPeerGUID. * * Throws BusError an error status. UNKNOWN_GUID if there is no authenticated peer * with the specified GUID. Other error status codes indicating a failure. * * \param guid the GUID of a remote authenticated peer * \param cb A callback function that will be sent the time in seconds relative to the * current time when the keys will expire */ void getKeyExpiration(DOMString guid, timeoutCallback cb); /** * \brief Adds a logon entry string for the requested authentication mechanism to the key store. * * This allows an authenticating server to generate offline authentication * credentials for securely logging on a remote peer using a user-name and password * credentials pair. This only applies to authentication mechanisms that support a * user name + password logon functionality. * * \param authMechanism the authentication mechanism * \param userName the user name to use for generating the logon entry * \param password the password to use for generating the logon entry. If the * password is null the logon entry is deleted from the key * store. * \param cb callback function that should be run after the logonEntry has * been added. Status will be OK if the logon entry was generated. * BUS_INVALID_AUTH_MECHANISM if the authentication mechanism * does not support logon functionality. * Other error status codes indicating a failure. */ void addLogonEntry(DOMString authMechanism, DOMString userName, DOMString password, statusCallback cb); /** * \brief Gets the peer GUID for this peer or an authenticated remote peer. * * Peer GUIDs are used by the authentication mechanisms to uniquely and identify a * remote application instance. The peer GUID for a remote peer is only available if * the remote peer has been authenticated. * * \param name name of a remote peer or null to get the local (our) peer * GUID * \param cb callback that will contain the guid for the local or remote peer depending on the value of name */ void getPeerGUID(DOMString name, guidCallback cb); /** * \brief Check to see if peer security has been enabled for this bus attachment. * * \param cb callback which indicates if peer security is enabled */ void getPeerSecurityEnabled(securityEnabledCallback cb); /** * \brief Gets a proxy to a remote bus object. * * \param name the name, object path, and optional arguments of the remote object of the * form "org.sample.Foo/foo:sessionId=42" where "org.sample.Foo" is the * well-known or unique name, "/foo" is the object path, and ":sessionId=42" is * the optional session ID the be used for communicating with the remote object * \param cb a callback containing a proxy to the remote bus object at the name and object path */ void getProxyBusObject(DOMString name, proxyBusObjectCallback cb); /** * \brief Returns the current non-absolute real-time clock used internally by AllJoyn. * * This value can be compared with the timestamps on messages to calculate the * time since a timestamped message was sent. * * \param cb callback function that will contain the current timestamp in milliseconds. */ void getTimestamp(timestampCallback cb); }; /** * \brief callback function containing a status code * * When the previous method call was successful status will be undefined or null * \param status AllJoyn status code */ callback statusCallback = void (Status status); /** * \brief callback function containing the status code and SessionPort * * \param status AllJoyn status code * \param port The sessionPort assigned as a result of the bindSessionPort method call. */ callback sessionPortCallback = void (Status status, SessionPort port); /** * \brief callback function containing the status code and the InterfaceDescription * * \param status AllJoyn status code * \param interfaceDescription an AllJoyn InterfaceDescription */ callback interfaceDescriptionCallback = void (Status status, InterfaceDescription interfaceDescription); /** * \brief callback function containing the status code and a collection of InterfaceDescritptions * * \param status AllJoyn status code * \param interfaceDescriptions an array of interfaceDescriptions * \param numIfaces the number of interfaces in the interfaceDescriptions param. */ callback interfaceDescriptionsCallback = void (Status status, InterfaceDescriptions[] interfaceDescriptions, unsigned long numIfaces); /** * \brief callback function containing the time in seconds relative to the current time when the keys will expire * * \param status AllJoyn status code * \param timeout The time in seconds relative to the current time when the keys will expire */ callback timeoutCallback = void (Status status, unsigned long timeout); /** * \brief Returns the guid for the local or remote peer * * \param status AllJoyn status code * \param guid the guid string for the local or remote peer */ callback guidCallback = void (Status status, DOMString guid); /** * \brief true if peer security has been enabled, false otherwise. * * \param status AllJoyn status code * \param enabled true if peer security has been enabled, false otherwise. */ callback securityEnabledCallback = void (Status status, boolean enabled); /** * \brief callback function containing status code and proxyBusObject * * \param status AllJoyn status code * \param proxyBusObject the requested ProxyBusObject */ callback proxyBusObjectCallback = void (Status status, ProxyBusObject proxyBusObject); /** * \brief callback function containing the current timestamp in milliseconds * * \param status AllJoyn status code * \param timestamp The current timestamp in milliseconds */ callback timestampCallback = void (Status status, unsigned long timestamp); /** * \brief callback function containing the socket file descriptor for a session * * \param status AllJoyn status code * \param socketFd socket fild descriptor for a session */ callback socketFdCallback = void (Status status, SocketFd socketFd); /** * \brief callback function indicating if name ownership was able to be determined * * \param status AllJoyn status code * \param hasOwner true if name exists on the bus. if status is not OK the hasOwner * parameter is not modified. */ callback hasOwnerCallback = void(Status status, boolean hasOwner); /** * \brief callback function indicating the number of second that a link can be unresponcive * * \param status AllJoyn status code: * OK if successful * ALLJOYN_SETLINKTIMEOUT_REPLY_NOT_SUPPORTED if local daemon does not support SetLinkTimeout * ALLJOYN_SETLINKTIMEOUT_REPLY_NO_DEST_SUPPORT if SetLinkTimeout not supported by destination * BUS_NO_SESSION if the Session id is not valid * ALLJOYN_SETLINKTIMEOUT_REPLY_FAILED if SetLinkTimeout failed * BUS_NOT_CONNECTED if the BusAttachment is not connected to the daemon * \param linkTimeout this value will be the resulting (possibly upward) adjusted linkTimeout * value that is acceptable to the underlying transport. */ callback linkTimeoutCallback = void (Status status, unsigned long linkTimeout); /** * \brief A BusListener is called by AllJoyn to inform users of bus related events. * * All operations of the interface are optional. */ [NoInterfaceObject] callback interface BusListener { /** * \brief Called by the bus when the listener is registered. * * \param busAttachment the bus the listener is registered with */ void onRegistered(BusAttachment busAttachment); /** * \brief Called by the bus when the listener is unegistered. */ void onUnregistered(); /** * \brief Called by the bus when an external bus is discovered that is advertising a * well-known name that this attachment has registered interest in via a DBus call to * org.alljoyn.Bus.FindAdvertisedName * * \param name a well known name that the remote bus is advertising * \param transport transport that received the advertisment * \param namePrefix the well-known name prefix used in call to FindAdvertisedName that * triggered this callback */ void onFoundAdvertisedName(DOMString name, TransportMask transport, DOMString namePrefix); /** * \brief Called by the bus when an advertisement previously reported through FoundName has * become unavailable. * * \param name a well known name that the remote bus is advertising that is of interest to * this attachment * \param transport transport that stopped receiving the given advertised name * \param namePrefix the well-known name prefix that was used in a call to * FindAdvertisedName that triggered this callback */ void onLostAdvertisedName(DOMString name, TransportMask transport, DOMString namePrefix); /** * \brief Called by the bus when the ownership of any well-known name changes. * * \param busName the well-known name that has changed * \param previousOwner the unique name that previously owned the name or null if * there was no previous owner * \param newOwner the unique name that now owns the name or null if the there is * no new owner */ void onNameOwnerChanged(DOMString busName, DOMString previousOwner, DOMString newOwner); /** * \brief Called by the bus when the value of a property changes if that property has annotation * * \param propName The property name that has changed. * \param propValue The new value of the property; NULL if not present. */ void onPropertyChanged(DOMString propName, any propValue); /** * \brief Called when a BusAttachment this listener is registered with is stopping */ void onStopping(); /** * \brief Called when a BusAttachment this listener is registered with is has become * disconnected from the bus. */ void onDisconnected(); }; /** * A bus object is a native object with attributes for each implemented interface: * <dl> * <dt><