IDL Author's Guide - Rules and Syntax

An interface is declared with the interface keyword, and the simplest possible interface is as follows:


interface nsIFoo {
};
	

To specify an interface's parent, follow the interface name with a colon and the parent name:


interface nsIFoo : nsIParent {
};
	

In XPCOM, all interfaces have an associated IID. Use the identifier attribute syntax to specify the uuid attribute:


[
    uuid(00000000-0000-0000-c000-000000000046)
]
interface nsIFoo : nsIParent {
};
	

If you wish to have a forward declaration for an interface, simply omit the interface definition and all parent and attribute data:


interface nsIForward;
        

An interface can have both methods and attributes. Attributes are properties of interface objects, which can be read and optionally set. The following is an interface with one method (no return value, no parameters) named fun and an integer-valued attribute named attr:

interface nsIFoo {
    attribute long attr;
    void fun();
};
      

Methods can have any number of in, out or inout parameters, with a variety of types. The following interface shows parameters of different types and ``in-out-ness''²:


interface nsIStringStuff {
  void FindStringLength(in string str, out long l);
  void ConcatenateStrings(in string str1, in string str2,
                          out string result);
  void ReplaceChar(inout string str, in char from, in char to,
                   in boolean foldCase);
};
       

You can specify a non-void return type for your method, but you should be aware of the code-generation rules. A non-void return type is converted to a trailing out parameter when the C++ is generated :


interface nsINonVoidReturn {
  string GimmeString(in string str, in long count);
  long GimmeLong(in boolean prime);
};
        

Attributes can be made read-only, by prepending the readonly keyword to the definition :


interface nsIThing {
  readonly attribute string LookButDontTouch;
};
        

C++ get and set methods for attributes are automatically declared for attributes in the interface. An attribute name foo generates accessor methods GetFoo and SetFoo. Notice that the first letter of the attribute is changed to uppercase for the accessor method.

XPIDL code	Generated C++ header
interface nsIBar { attribute short foo; }	/* starting interface: nsIBar */ class nsIBar : { public: /* attribute short foo; */ NS_IMETHOD GetFoo(PRInt16 *aFoo) = 0; NS_IMETHOD SetFoo(PRInt16 aFoo) = 0; };

XPIDL provides several built-in types. The use of native types is also possible, though this may limit scriptability.

Type	C++ mapping
void	void
boolean	PRBool
octet	PRUint8
short	PRInt16
long	PRInt32
long long	PRInt64
unsigned short	PRUint16
unsigned long	PRUint32
unsigned long long	PRUint64
float	float
double	double
char	char
wchar	PRUnichar
string	char*
wstring	PRUnichar*

It is possible to use native types in XPIDL by declaring then using the native declaration syntax which works similar to a typedef in C++.

A native type can be given a name using the following syntax:
native name(native_type);

It is also possible to define reference and pointer types by combining [ref] or [ptr] with native:

XPIDL code	Generated C++
native nsNativeFile(nsFileSpec); [ref] native nsNativeFilePtr(nsFileSpec); [ptr] native nsNativeFileRef(nsFileSpec); interface foo { void Open(in nsNativeFile aFileSpec); void OpenByRef(in nsNativeFileRef aFileSpecRef); void OpenByPtr(in nsNativeFilePtr aFileSpecPtr); };	/* starting interface: foo */ class foo { public: /* void Open (in nsNativeFile aFileSpec); */ NS_IMETHOD Open(nsFileSpec aFileSpec) = 0; /* void OpenByRef (in nsNativeFileRef aFileSpecRef); */ NS_IMETHOD OpenByRef(nsFileSpec * aFileSpecRef) = 0; /* void OpenByPtr (in nsNativeFilePtr aFileSpecPtr); */ NS_IMETHOD OpenByPtr(nsFileSpec & aFileSpecPtr) = 0; };

Using native types in your code can be a good way to migrate existing interfaces. However, using native types in a method may mean that method is not scriptable.

When referencing interfaces defined in other files, you must #include "filename.idl" In XPIDL, #include only includes the file once, so the #include statement does not need to be protected by ifdefs as with the C preprocessor.

C-style enumerations are not supported, since the size of enums can be compiler-specific. Instead XPIDL supports defining constants that appear in the C++ and JavaScript mappings. Constants must be of type short or long, and must appear inside an interface declaration.

Other types are not supported for constants since they do not map into all languages or have memory management issues. To define a "constant" that is not a short or long, write a method that returns the value, or put the value into an attribute.

XPIDL code	C++ code
const short c1 = 1+1;	enum { c1 = 2 };
const short c2 = c1 * 5;	enum { c2 = 10 };
const long flag = 1 << 5;	enum { flag = 32 };
const float invalid_constant = 6.0;	Warning: const decl 'invalid_constant' was not of type short or long, ignored

[Rules and Syntax] [Best Practices] [Keywords]