An interface definition has a name, and one or more attributes, methods, or events. An interface's name is defined with the interface element's mandatory name attribute. This name is used when referring to the inherited interface from other interface definitions, as well as in the server and various client environments. The other characteristics of an interface are defined using child elements of the interface element.
Each method in an interface is defined by a method element. The name of a method is defined by this element's mandatory name attribute. The other properties of a method are defined by child elements of the method.
If a method has a return value, it is defined using a single result element. The type of the return value is specified in the same way the type is specified for a structure field. If no result element is present, the method has no return value.
If a method can fail for an API-specific reason, it is defined using a single error element. The type of an error is specified the same way the type is specified for a structure field. Unlike a structure field, an error need not specify a type. Such a situation is indicated by an error element with no attributes or child elements. If no error element is present, the method will only fail if there is a connectivity problem between the client and the server.
A method's arguments are defined, in order, with zero or more argument elements. Each argument element has a mandatory name attribute. The type of an argument is specified in the same way the type is specified for a structure field.
Example 4-4 Method Definition<struct name="Meal">...</struct>
<struct name="Ingredient">...</struct>
<method name="cook">
<result typeref="Meal" />
<error />
<argument type="string" name="name" nullable="true" />
<argument name="ingredients">
<list typeref="Ingredient" />
</argument>
</method>
Each attribute in an interface is defined by a property element. The name of an attribute is defined by this element's mandatory name attribute. The types of access permitted are defined by the mandatory access attribute, which takes a value of ro, wo, or rw, corresponding to read-only access, write-only access, or read-write access, respectively.
The type of an attribute is specified in the same way the type is specified for a structure field.
If access to an attribute can fail for an API-specific reason, it is defined using one or more error elements. An error element in a property may specify a for attribute, which takes a value of ro, wo, or rw, corresponding to the types of access the error return definition applies to. An error element with no for attribute is equivalent to one with a for attribute set to the access level defined on the property. Two error elements may not specify overlapping access types. For example, on a read-write property it is invalid for one error to have no for attribute (implying rw) and one to have a for attribute of wo they both specify an error for writing.
The type of an error is specified the same way the type is specified for a method. It is identical to defining the type of a structure, with the exception that a type need not be defined.
Example 4-5 Attribute Definition<struct name="PrivilegeError">...</struct>
<property name="guestList" access="rw">
<list type="string" />
<error for="wo" typeref="PrivilegeError" />
<!-- Reads cannot fail -->
</property>
Each event in an interface is defined by a event element. The name of an event is defined by this element's mandatory name attribute. The type of an event is specified in the same way the type is specified for a structure field.
Example 4-6 Event Definition<struct name="TremorInfo">...</struct> <event name="earthquakes" typeref="TremorInfo" />