/*
 * 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><b>IDL type</b></th><th><b>DBus type</b></th><th><b>Signature</b></th><th><b>JavaScript
 * type</b></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 <em>parseInt</em> 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 <em>parseInt</em> 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&lt;T&gt;</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&lt;any&gt;</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 <em>"value"</em>.  Nested VARIANTs will
 * remove only one VARIANT wrapper.  For example, a VARIANT of a VARIANT of a string will be the
 * Object <em>{ "s": "value" }</em>.</td></tr>
 * </table>
 *
 * Debug output of the plugin can be configured dynamically by setting the debug attribute of the
 * <em>object</em> element containing the plugin.  The syntax of the attribute value is the same as
 * BusAttachment.setDaemonDebug, e.g. <em>debug="ALLJOYN_JS=15"</em>.  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 <em>true</em> if this attachment is allowed to receive messages
  *                            from remote devices.  Defaults to <em>false</em>.
  */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.
     *
     * <em>null</em> 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
     * <em>unregisterSignalHandler</em> 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 <em>registerSignalHandler</em>.
     *
     * \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 <em>0</em>.
     * \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><em>port</em></dt>
     * <dd>SessionPort value to bind.  The default value is <em>SESSION_PORT_ANY</em> to allow
     * this operation to choose an available port.  On successful return, this value will
     * be the chosen port.</dd>
     * <dt><em>traffic</em></dt>
     * <dd>TrafficType.  The default value is <em>TRAFFIC_MESSAGES</em>.</dd>
     * <dt><em>isMultipoint</em></dt>
     * <dd>boolean indicating if session is multi-point capable.  The default value is
     * <em>false</em>.</dd>
     * <dt><em>proximity</em></dt>
     * <dd>Proximity.  The default value is <em>PROXIMITY_ANY</em>.</dd>
     * <dt><em>transports</em></dt>
     * <dd>TransportMask of the allowed transports.  The default value is
     * <em>TRANSPORT_ANY</em>.</dd>
     * <dt><em>onAccept</em></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><em>onJoined</em></dt>
     * <dd>a <a href="#::ajn::SessionJoinedListener">SessionJoinedListener</a> called by the bus
     * when a session has been successfully joined</dd>
     * <dt><em>onLost</em></dt>
     * <dd>a <a href="#::ajn::SessionLostListener">SessionLostListener</a> called by the bus
     * when an existing session becomes disconnected</dd>
     * <dt><em>onMemberAdded</em></dt>
     * <dd>a <a href="#::ajn::SessionMemberAddedListener">SessionMemberAddedListener</a> called 
     * by the bus when a member of a multipoint session is added</dd>
     * <dt><em>onMemberRemoved</em></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><em>onLost</em></dt>
     * <dd>a <a href="#::ajn::SessionLostListener">SessionLostListener</a> called by the bus
     * when an existing session becomes disconnected</dd>
     * <dt><em>onMemberAdded</em></dt>
     * <dd>a <a href="#::ajn::SessionMemberAddedListener">SessionMemberAddedListener</a> called 
     * by the bus when a member of a multipoint session is added</dd>
     * <dt><em>onMemberRemoved</em></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
     *                 <em>null</em> 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><em>host</em></dt>
     * <dd>mandatory bus name of the attachment that is hosting the the session to be joined</dd>
     * <dt><em>port</em></dt>
     * <dd>mandatory SessionPort of host to be joined</dd>
     * <dt><em>traffic</em></dt>
     * <dd>TrafficType.  The default value is <em>TRAFFIC_MESSAGES</em>.</dd>
     * <dt><em>isMultipoint</em></dt>
     * <dd>boolean indicating if session is multi-point capable.  The default value is
     * <em>false</em>.</dd>
     * <dt><em>proximity</em></dt>
     * <dd>Proximity.  The default value is <em>PROXIMITY_ANY</em>.</dd>
     * <dt><em>transports</em></dt>
     * <dd>TransportMask of the allowed transports.  The default value is
     * <em>TRANSPORT_ANY</em>.</dd>
     * <dt><em>onLost</em></dt>
     * <dd>a <a href="#::ajn::SessionLostListener">SessionLostListener</a> called by the bus
     * when an existing session becomes disconnected</dd>
     * <dt><em>onMemberAdded</em></dt>
     * <dd>a <a href="#::ajn::SessionMemberAddedListener">SessionMemberAddedListener</a> called
     * by the bus when a member of a multipoint session is added</dd>
     * <dt><em>onMemberRemoved</em></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
     * <b>lot</b> 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 <em>null</em> 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 <em>null</em> 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 <em>null</em> if
     *                      there was no previous owner
     * \param newOwner the unique name that now owns the name or <em>null</em> 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><em>interfaceName</em></dt>
 * <dd>A native object implementing the named interface</dd>
 * </dl>
 *
 * Each interface implementation is a native object with attributes for each method or property:
 * <dl>
 * <dt><em>methodName</em></dt>
 * <dd>A <a href="#::ajn::MessageListener">MessageListener</a></dd>
 * <dt>get <em>propertyName</em></dt>
 * <dd>A JavaScript getter for the named property</dd>
 * <dt>set <em>propertyName</em>(value)</dt>
 * <dd>A JavaScript setter for the named property</dd>
 * </dl>
 * <a href="#::ajn::SignalEmitter">SignalEmitter</a> attributes are added to the native
 * object for each signal of the implemented interface when the object is registered.  The
 * name of each attribute is the name of the signal.
 *
 * Optionally, a bus object may have the following attributes:
 * <dl>
 * <dt><em>toXML</em>(deep, indent)</dt>
 * <dd>A native function, taking two parameters, that is called by the bus when the object
 * is introspected.  This function can be provided in order to customize the introspection
 * XML presented to remote nodes.  Note that the DTD description and the root element are
 * not generated.  The first parameter, deep, indicates whether to include XML for all
 * decendents rather than stopping at direct children.  The second parameter, indent, is the
 * number of characters to indent the XML.</dd>
 * <dt><em>onRegistered</em></dt>
 * <dd>A native function, taking no parameters, that is called by the bus when the object
 * has been successfully registered. The object can perform any initialization such as
 * adding match rules at this time.</dd>
 * <dt><em>onUnregistered</em></dt>
 * <dd>A native function, taking no parameters, that is called by the bus when the object
 * has been successfully unregistered.</dd>
 * </dl>
 *
 * <em>this</em> in all bus object callbacks is the bus object.
 */
[NoInterfaceObject]
callback interface BusObject {
    /**
     * Called by the message bus when the object has been successfully registered. The object can
     * perform any initialization such as adding match rules at this time.
     */
    void onRegistered();
    /**
     * Called by the message bus when the object has been successfully unregistered
     */
    void onUnregistered();
    /**
     * \brief Emits a signal.
     *
     * The arguments are as described in <a href="#::ajn::ProxyMethod">ProxyMethod</a>,
     * with one exception.  An optional additional argument containing parameters controlling
     * the signal emission can be provided.  The additional argument is a native object with
     * optional attributes:
     * <dl>
     * <dt><em>sessionId</em></dt>
     * <dd>The sessionId to use for this emission or 0 for any</dd>
     * <dt><em>destination</em></dt>
     * <dd>The unique or well-known bus name or the signal recipient</dd>
     * <dt><em>timeToLive</em></dt>
     * <dd>If non-zero this specifies the useful lifetime for this signal. 
	 * The units are milliseconds for non-sessionless signals and seconds for sessionless signals.
	 * If delivery of the signal is delayed beyond the timeToLive due to network congestion or
     * other factors the signal may be discarded. There is no guarantee that expired signals
     * will not still be delivered.</dd>
     * <dt><em>flags</em></dt>
     * <dd>The logical OR of the message flags (ALLJOYN_FLAG_* constants) for this
     * signal</dd>
     * </dl>
     * \param interfaceName the name of the interface that will emit the signal
     * \param signalName the name of the signal
     * \param args the message arguments.  The type of the arguments is determined by the method
     *             or signal signature.
     * \param params see above
     * \param cb callback called once the signal has been emitted.
     */
    void signal(DOMString interfaceName, DOMString signalName, any... args, optional object params, statusCallback cb);
};

/**
 * \brief Generic interface for describing different authentication credentials.
 */
dictionary Credentials {
    /** 
     * \brief Indicates credentials include a password, pincode, or passphrase.
     */
    const unsigned short PASSWORD = 0x0001;
    /** 
     * \brief Indicates credentials include a user name.
     */
    const unsigned short USER_NAME = 0x0002;
    /** 
     * \brief Indicates credentials include a chain of PEM-encoded X509
     * certificates.
     */
    const unsigned short CERT_CHAIN = 0x0004; 
    /** 
     * \brief Indicates credentials include a PEM-encoded private key.
     */
    const unsigned short PRIVATE_KEY = 0x0008; 
    /** 
     * \brief Indicates credentials include a logon entry that can be used to logon a
     * remote user.
     */
    const unsigned short LOGON_ENTRY = 0x0010;
    /**
     * \brief Indicates credentials include an expiration time
     */
    const unsigned short EXPIRATION = 0x0020;
    /** 
     * \brief Indicates the credential request is for a newly created password.  This
     * value is only used in a credential request. 
     */
    const unsigned short NEW_PASSWORD = 0x1001; 
    /**
     * \brief Indicates the credential request is for a one time use password.  This
     * value is only used in a credential request. 
     */
    const unsigned short ONE_TIME_PWD = 0x2001; 

    /**
     * \brief A requested password, pincode, or passphrase.
     *
     * <em>undefined</em> if not set.
     */
    DOMString password;
    /**
     * \brief A requested user name.
     *
     * <em>undefined</em> if not set.
     */
    DOMString userName;
    /**
     * \brief A requested public key certificate chain. 
     * 
     * The certificates must be PEM encoded.
     *
     * <em>undefined</em> if not set.
     */
    DOMString certChain;
    /**
     * \brief A requested private key. 
     *
     * The private key must be PEM encoded and may be encrypted. If the private key is
     * encrypted the passphrase required to decrypt it must also be supplied.
     *
     * <em>undefined</em> if not set.
     */
    DOMString privateKey;
    /**
     * \brief A logon entry. 
     *
     * For example for the Secure Remote Password protocol in RFC 5045, a logon entry
     * encodes the N,g, s and v parameters. An SRP logon entry string has the form
     * N:g:s:v where N,g,s, and v are ASCII encoded hexadecimal strings and are
     * separated by colons.
     *
     * <em>undefined</em> if not set.
     */
    DOMString logonEntry;
    /**
     * \brief An expiration time in seconds relative to the current time for the
     * credentials.
     *
     * This value is optional and can be set on any response to a credentials
     * request. After the specified expiration time has elapsed any secret keys based on
     * the provided credentials are invalidated and a new authentication exchange will
     * be required. If an expiration is not set the default expiration time for the
     * requested authentication mechanism is used.
     *
     * <em>undefined</em> if not set.
     */
    unsigned long expiration;
};

/**
 * \brief Function invoked when the asynchronous call completes with an error.
 *
 * This callback interface is used in asynchronous operations such as introspecting remote DBus
 * objects and invoking remote methods.
 *
 * <em>this</em> is the ProxyBusObject on which the method or introspection call was made
 * with this callback.
 *
 * \param error the error.
 */
callback ErrorListener = void (BusError error);

/**
 * \brief Describes the methods, signals and properties of a BusObject or
 * ProxyBusObject.
 */
dictionary InterfaceDescription {
    /**
     * \brief The method descriptions of the interface.
     */
    MethodDescription[] method;
    /**
     * \brief The signal descriptions of the interface.
     */
    SignalDescription[] signal;
    /**
     * \brief The property descriptions of the interface.
     */
    PropertyDescription[] property;
    /**
     * \brief Indicates if this interface is secure. 
     *
     * Secure interfaces require end-to-end authentication.  The arguments for methods
     * calls made to secure interfaces and signals emitted by secure interfaces are
     * encrypted.
     *
     * The default value is <em>false</em>.
     */
    boolean secure;
};

/**
 * \brief The function invoked when the asynchronous joinSession call completes
 * successfully.
 *
 * This callback is only used by session joiners.
 *
 * \param id unique identifier for session
 * \param opts session options
 */
callback JoinSessionSuccessListener = void (SessionId id, SessionOpts opts);

/**
 * \brief Message context.
 *
 * This interface contains additional information about a received DBus message.  It is provided
 * in remote method replys, received remote method calls, and received signals.
 */
interface Message {
    /** No reply is expected*/
    const octet ALLJOYN_FLAG_NO_REPLY_EXPECTED = 0x01;
    /** Auto start the service */
    const octet ALLJOYN_FLAG_AUTO_START = 0x02;
    /** Allow messages from remote hosts (valid only in Hello message) */
    const octet ALLJOYN_FLAG_ALLOW_REMOTE_MSG = 0x04;
    /** Global (bus-to-bus) broadcast */
    const octet ALLJOYN_FLAG_GLOBAL_BROADCAST = 0x20;
    /** Header is compressed */
    const octet ALLJOYN_FLAG_COMPRESSED = 0x40;
    /** Body is encrypted */
    const octet ALLJOYN_FLAG_ENCRYPTED = 0x80;

    /**
     * \brief <em>true</em> if the message is unreliable. 
     * 
     * Unreliable messages have a non-zero time-to-live and may be silently discarded.
     *
     * Read-only.
     */
    readonly attribute boolean isUnreliable;
    /**
     * \brief The name of the authentication mechanism that was used to generate the encryption
     * key if the message is encrypted.
     *
     * Read-only.
     *
     * <em>undefined</em> if the header is not present.
     */
    readonly attribute DOMString authMechanism;
    /**
     * \brief The signature for this message.
     *
     * Read-only.
     *
     * <em>undefined</em> if the header is not present.
     */
    readonly attribute DOMString signature;
    /**
     * \brief The AllJoyn object path string stored in the AllJoyn header field.
     *
     * Read-only.
     *
     * <em>undefined</em> if the header is not present.
     */
    readonly attribute DOMString objectPath;
    /**
     * \brief The AllJoyn interface string stored in the AllJoyn header field.
     *
     * Read-only.
     *
     * <em>undefined</em> if the header is not present.
     */        
    readonly attribute DOMString interfaceName;
    /**
     * \brief The AllJoyn member (method/signal) name string stored in the AllJoyn header field.
     *
     * Read-only.
     *
     * <em>undefined</em> if the header is not present.
     */        
    readonly attribute DOMString memberName;
    /**
     * \brief The sender's well-known name string stored in the AllJoyn header field.
     *
     * Read-only.
     *
     * <em>undefined</em> if the header is not present.
     */
    readonly attribute DOMString sender;
    /**
     * \brief The message destination string stored in the AllJoyn header field.
     *
     * Read-only.
     *
     * <em>undefined</em> if the header is not present.
     */
    readonly attribute DOMString destination;
    /**
     * \brief The flags for the message.
     *
     * Read-only.
     */
    readonly attribute octet flags;
    /**
     * \brief The session id for the message.
     *
     * Read-only.
     *
     * 0 'zero' if sender did not specify a session.
     */
    readonly attribute SessionId sessionId;

    /**
     * \brief Replies to a method call.
     *
     * Only valid in method callbacks.
     *
     * The reply arguments are as described in <a href="#::ajn::ProxyMethod">ProxyMethod</a>.
     *
     * \param args the reply arguments.  The type of the arguments is determined by the method
     *             reply signature.
     * \param cb the callback function run once the reply has been sent
     */
    void reply(any... args, statusCallback cb);
    /* 
     * TODO Web IDL doesn't define exception constructors, so instead of one
     * replyError(in BusError error), there are two operations below.
     */
    /**
     * \brief Replies to a method call with an error status.
     *
     * Only valid in method callbacks.
     *
     * \param code the status code for the error
     * \param code the callback function once the replyError has been sent
     */
    void replyError(Status code, statusCallback cb);
    /**
     * \brief Replies to a method call with an error message.
     *
     * Only valid in method callbacks.
     *
     * \param name the name of the error.  The error name must follow the same restrictions as
     *             DBus interface names.
     * \param message an error message string
     * \param cb the callback function run once the reply has been sent.
     */
    void replyError(DOMString name, optional DOMString message, statusCallback cb);
};

/**
 * \brief Function invoked when the method call, reply, or signal is received.
 *
 * <em>this</em> depends on what context this function is in invoked under:
 * <dl>
 * <dt>Method call</dt>
 * <dd>The registered bus object implementing the method</dd>
 * <dt>Method reply</dt>
 * <dd>The ProxyBusObject the method call was called upon</dd>
 * <dt>Signal</dt>
 * <dd>The BusAttachment the signal handler was added upon</dd>
 * </dl>
 *
 * This callback is used in asynchronous method or signal operations.
 *
 * \param context the message headers
 * \param args the message arguments.  The type of the arguments is determined by the method
 *             or signal signature.
 */
callback MessageListener = void (Message context, any... args);

/**
 * \brief Object representing a method of an interface.
 */
dictionary MethodDescription {
    /**
     * \brief Mandatory string that is the remotely-visible method name.
     */
    DOMString name;
    /**
     * \brief Optional string describing the method's input argument types.
     */
    DOMString signature;
    /**
     * \brief Optional string describing the method's output argument types.
     */
    DOMString returnSignature;
    /**
     * \brief Optional string describing the method's argument names, listed input
     * argument names first.
     */
    DOMString argNames;
};

/**
 * \brief Object representing a property of an interface.
 */
dictionary PropertyDescription {
    /**
     * \brief Mandatory string that is the remotely-visible property name.
     */
    DOMString name;
    /**
     * \brief Mandatory string describing the property's type.
     */
    DOMString signature;
    /**
     * \brief Mandatory string that may be "readwrite", "read", or "write".
     */
    DOMString access;
};

/**
 * \brief Proxy bus object.
 *
 * Each ProxyBusObject instance represents a single DBus/AllJoyn object registered somewhere on
 * the bus. ProxyBusObjects are used to make method calls on these remotely located DBus
 * objects.
 */
[NoInterfaceObject]
interface ProxyBusObject {
    /**
     * \brief The absolute object path for the remote object.
     *
     * Read-only.
     */
    readonly attribute DOMString path;
    /**
     * \brief The remote service name for this object.  Typically a well-known service name, but
     * may be a unique name.
     *
     * Read-only.
     */
    readonly attribute DOMString serviceName;
    /**
     * \brief the session Id for this object
     *
     * Read-only
     */
    readonly attribute SessionId sessionId;

    /**
     * Obtains an array of ProxyBusObjects for the children of this ProxyBusObject.
     *
     * \param cb callback that contains an array of children to this ProxyBusObject
     */
    getter getChildren(childrenCallback cb);
    /**
     * \brief Gets a proxy to remote bus object interface.
     *
     * \param interfaceName the name of the interface
     * \param cb callback containing a interfaceDescription of the remote object
     */
    getter getInterface(DOMString interfaceName, interfaceDescriptionCallback cb);
    /**
     * \brief Gets returns all the interfaces found on this object
     * 
     * \param cb callback containing an array of interfaceDescriptions found by this proxyBusObject
     */
    getter getInterfaces(interfaceDescriptionsCallback cb);
                
    /**
     * \brief Query the remote object on the bus to determine the interfaces and children that
     * exist. 
     * This information is used to populate this object's interfaces and children.
     *
     * \param cb callback indicating success or failure of the introspect
     */
    void introspect(statusCallback cb);
    /**
     * \brief Invokes a remote bus object method.
     *
     * The remote method is invoked asynchronously.  The parameters to the remote method will be
     * coerced into DBus values from JavaScript values.  Special cases are identified in the
     * following list.
     * <dl>
     * <dt><em>INT64</em></dt><dd>The value is coerced into a string and then converted into an
     * INT64 value.  This allows representation of integers larger than allowed by JavaScript's
     * built-in number type.</dd>
     * <dt><em>UINT64</em></dt><dd>The value is coerced into a string and then converted into a
     * UINT64 value.  This allows representation of integers larger than allowed by JavaScript's
     * built-in number type.</dd>
     * <dt><em>ARRAY</em></dt><dd>When the DBus type is an array of DICT_ENTRY, an object where
     * each object property/value is a DBus key/value pair.  Otherwise, an Array object.  For
     * example, DBus "a{si}" may be JavaScript { "key0": 0, "key1": 1 }, and DBus "as" may be
     * JavaScript ["member1", "member2"].</dd>
     * <dt><em>STRUCT</em></dt><dd>An Array object.  For example, DBus "(si)" may be JavaScript
     * ["element0", 1].</dd>
     * <dt><em>VARIANT</em></dt><dd>An object with one attribute.  The name of the attribute is
     * the DBus signature of the variant value, and the value of the attribute is the VARIANT
     * value.  For example, DBus "v" may be JavaScript { "s": "value" }</dd>
     * </dl>
     *
     * Types may be nested, DBus "a{s(ii)}" may be JavaScript { "key0": [ 1, 2 ], "key1": [ 3, 4 ]
     * }.
     *
     * An optional additional argument containing parameters controlling the method call can
     * be provided.  The additional argument is a native object with optional attributes:
     * <dl>
     * <dt><em>timeout</em></dt>
     * <dd>the timeout specified in milliseconds to wait for a reply</dd>
     * <dt><em>flags</em></dt>
     * <dd>The logical OR of the message flags (ALLJOYN_FLAG_* constants) for this
     * method</dd>
     * </dl>
     *
     * \param interfaceName the name of the interface the method being called belongs to.
     * \param methodName the name of the method being called.
     * \param args the method arguments.  The type of the arguments is determined by the method
     *             signature.
     * \param cb callback function run after methodCall has been made
     */
    void methodCall(DOMString interfaceName, DOMString methodName, any... args, statusCallback cb);
    /**
     * \brief Introspect the remote object (across AllJoyn) and use the introspection data to
     * populate this ProxyBusObject and any descendant ProxyBusObjects (stored in this object's
     * children container) that are mentioned in the introspection data.
     *
     * Calling this operation does several things:
     * <ul>
     * <li> 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".)</li>
     * <li> Add all the interfaces mentioned in the introspection data to this ProxyBusObject.</li>
     * <li> Recursively create any child ProxyBusObject(s) and create/add their associated
     *      interfaces as mentioned in the XML. Then add the descendant object(s) to the
     *      appropriate descendant of this ProxyBusObject (in the children collection). If the
     *      named child object already exists as a child of the appropriate ProxyBusObject, then
     *      it is updated to include any new interfaces or children mentioned in the XML.</li>
     * </ul>
     *
     * Note that when this operation fails during parsing, the operation will return an
     * error <em>Status</em>.  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 source the XML
     * \param cb callback function specifying:
     *           OK if parsing is completely successful.
     *           An error status otherwise.
     */
    void parseXML(DOMString source, statusCallback cb);
    /**
     * \brief 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.
     *
     * Notification of success or failure is via the AuthListener passed to
     * enablePeerSecurity.
     * 
     * \param forceAuth If <em>true</em>, forces a re-authentication even if the peer
     *                  connection is already authenticated.  Defaults to
     *                  <em>false</em>.
     * \param cb callback function indicating:
     *           OK if securing could begin.
     *           BUS_NO_AUTHENTICATION_MECHANISM if enablePeerSecurity has not been called.
     *           Other error status codes indicating a failure.
     */
    void secureConnection(optional boolean forceAuth, statusCallback cb);
};

/**
 * \brief callback containing an array of ProxyBusObjects that are children of the 
 *        host ProxyBusObject
 *
 * \param status Alljoyn status object
 * \param children and array of ProxyBusObjects
 */
callback childrenCallback = void (Status status, ProxyBusObject[] children);


/**
 * \brief Called by the bus when a session has been successfully joined. The session is now
 * fully up.
 *
 * 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 id ID of session
 * \param joiner unique name of the joiner
 */
callback SessionJoinedListener = void (SessionPort port, SessionId id, DOMString joiner);

/**
 * \brief Called by the bus when an existing session becomes disconnected.
 *
 * This callback is only used by session joiners.
 *
 * \param id ID of session that was lost
 */
callback SessionLostListener = void (SessionId id);

/**
 * \brief Called by the bus when a member of a multipoint session is added.
 *
 * \param id ID of session whose member(s) changed
 * \param uniqueName unique name of member who was added
 */
callback SessionMemberAddedListener = void (SessionId id, DOMString uniqueName);

/**
 * \brief Called by the bus when a member of a multipoint session is removed.
 *
 * \param id ID of session whose member(s) changed
 * \param uniqueName unique name of member who was removed
 */
callback SessionMemberRemovedListener = void (SessionId id, DOMString uniqueName);

/**
 * \brief Contains a set of parameters that define a session's characteristics.
 */
dictionary SessionOpts {
    /** Session carries message traffic. */
    const octet TRAFFIC_MESSAGES = 0x01;
    /** Session carries an unreliable (lossy) byte stream. */
    const octet TRAFFIC_RAW_UNRELIABLE = 0x02;
    /** Session carries a reliable byte stream. */
    const octet TRAFFIC_RAW_RELIABLE = 0x04;
    /**
     * \brief The traffic type.
     */
    octet traffic;

    /**
     * \brief Multi-point session capable.
     *
     * A session is multi-point if it can be joined multiple times to form a single session with
     * multi (greater than 2) endpoints. When false, each join attempt creates a new
     * point-to-point session.
     */
    boolean isMultipoint;

    /** Any proximity */
    const octet PROXIMITY_ANY      = 0xFF;
    /** Physical proximity */
    const octet PROXIMITY_PHYSICAL = 0x01;
    /** Network proximity */
    const octet PROXIMITY_NETWORK  = 0x02;
    /**
     * The default value is <em>PROXIMITY_ANY</em>.
     */
    octet proximity;

    /** No transports */
    const unsigned short TRANSPORT_NONE = 0x0000;
    /** Any transport */
    const unsigned short TRANSPORT_ANY = 0xFFFF;
    /** Local (same device) transport */
    const unsigned short TRANSPORT_LOCAL = 0x0001;
    /** Wireless local-area network transport */
    const unsigned short TRANSPORT_WLAN = 0x0004;
    /** Wireless wide-area network transport */
    const unsigned short TRANSPORT_WWAN = 0x0008;
    /** Wired local-area network transport */
    const unsigned short TRANSPORT_LAN = 0x0010;
    /**
     * \brief The allowed transports.
     */
    TransportMask transports;
};

/**
 * \brief Object representing a signal of an interface.
 */
dictionary SignalDescription {
    /**
     * \brief Mandatory string that is the remotely-visible signal name.
     */
    DOMString name;
    /**
     * \brief Optional string describing the signal's argument types.
     */
    DOMString signature;
    /**
     * \brief Optional string describing the signal's argument names, listed input
     * argument names first.
     */
    DOMString argNames;
};

/**
 * \brief The function invoked when the asynchronous call completes successfully.
 *
 * <em>this</em> is the ProxyBusObject on which the method or introspection call was made
 * with this callback.
 *
 * This callback is used in asynchronous operations such as introspecting remote DBus
 * objects.
 */
callback SuccessListener = void ();

/* 
 * TODO Web IDL doesn't allow DOMString constants, so make Version its own
 * object that needs to be constructed to get to the buildInfo and string
 * value of the version.
 */
[Constructor]
/**
 * \brief AllJoyn library version and build information.
 */
interface Version {
    /** 
     * \brief The build information of the AllJoyn library. 
     *
     * Read-only.
     */
    readonly attribute DOMString buildInfo;
    /** 
     * \brief The version of the AllJoyn library as a single number. 
     *
     * Read-only.
     *
     * The numeric version is composed of the architecture level, API level, and
     * release.
     */
    readonly attribute unsigned long numericVersion;
    /** 
     * \brief The architecture level. 
     *
     * Read-only.
     */
    readonly attribute unsigned long arch;
    /** 
     * \brief The API level. 
     *
     * Read-only.
     */
    readonly attribute unsigned long apiLevel;
    /** 
     * \brief The release. 
     *
     * Read-only.
     */
    readonly attribute unsigned long release;
    /** 
     * \brief The version of AllJoyn library.
     *
     * Read-only. 
     */
    readonly attribute DOMString version;
};