New nsIScriptable interface

This page has the technical details on the nsIScriptableObject interface.

Differences to IDispatch

We will *not* implement a number of "Visual Basic-isms" in IDispatch - specifically:

• no distinction between a "property put by value" and "property put by reference" (ie, VBs "let" vs "set"), and combining "property get" and "method call" in the flags will be illegal (ie, VB allows you to omit the parens when calling subroutines, making such calls indistinguishable from a property reference)

• names will all be case-sensitive.

Identifier mapping

Like MSCOM, integer IDs are used to identify attributes on an object. Functions are provided to convert from names to IDs, or from IDs to names.

The rules for IDs are:

• Once an ID has been assigned to a name, that ID must constant for that name for the life of the object.
• An ID can not be reused unless an attribute of the same name is recreated (ie, if an item is deleted from an object, the ID can not be reused for a different name)

MSCOM uses DISPIDs to refer to named params. The sementics for DISPIDs for names that appear only as params is unclear (the relevant MS docs need to be found)

nsIScriptableObject interface

Using XPCOM vocabulary (attribute for property, e.g.), the interface should look something like this (recall that xpidl capitalizes names for C++):

typedef PRUint32 nsDISPID;

[scriptable, uuid(...)]
interface nsIScriptableObject : nsISupports
{
    // Maps a single member name to its corresponding DISPID, which can then
    // be used on subsequent calls to invoke()
    nsDISPID getDispID(in AString aName);

    // Deletes a member by DISPID.
    void deleteMemberByDispID(in nsDISPID aDispID);

    // Adds a member and returns the dispid for the new item.
    nsDISPID addMemberByName(in AString aName);

    // Deletes a member by name.
    void deleteMemberByName(in AString aName);

    // Retrieves the name of a member.
    AString getMemberName(in nsDISPID aDispID);

    // Retrieves a member's properties.
    PRUint32 getMemberFlags(in nsDISPID aDispID);

    // Flags describing members.
    const PRUint32 MEMBER_METHOD      = 1; // member is a method
    const PRUint32 MEMBER_CONSTRUCTOR = 2; // member is a constructor
    const PRUint32 MEMBER_ATTRIBUTE   = 4; // member is an attribute
    const PRUint32 MEMBER_READONLY    = 8; // member is readonly

    // Retrieves the interface for the scope parent of an object.
    nsIScriptableObject getParentObject();

    // Enumerates the members of the object.
    nsDISPID getNextDispID(in PRUint32 aFlags, in nsDISPID aDispID);

    // Invoke a method or access an attribute exposed by an IScriptable.

    // XXX - semantics of DISPID and params is not clear.
    // presumably all possible param names must also provide
    // a dispid when asked.

    // MSCOM EXCEPTINFO param not used - existing
    // nsIExceptionService semantics should be used instead.

    nsIVariant invoke(in nsDISPID aDispID,
                      in PRUint32 aInvokeHow,
                      [array, size_is(aNumArgs)] in nsIVariant aArgs,
                      in PRUint32 aNumArgs,
                      [array, size_is(aNumNamedArgs)] in nsDISPID aNamedArgs,
                      in PRUint32 aNumNamedArgs);

    // Values for the aInvokeHow argument to invoke.
    const PRUint32 INVOKE_CALL      = 0; // invoke as a method
    const PRUint32 INVOKE_CONSTRUCT = 1; // invoke as a constructor
    const PRUint32 INVOKE_GETATTR   = 2; // get an attribute value
    const PRUint32 INVOKE_SETATTR   = 3; // set an attribute value

    // Predefined nsDISPID values
   /* DISPID reserved for the "value" property (ie, the 'default' value )*/
   const PRUint32 DISPID_VALUE = 0;
   /* DISPID reserved for the standard "NewEnum" method */
   const PRUint32 DISPID_NEWENUM = -4;

   const PRUint32 DISPID_CONSTRUCTOR = -6;
};