IDL Best Practices
We're currently working on this documentation. New stuff will be added on an ongoing basis. Please send any questions or comments to netscape.public.mozilla.xpcom.
enums and consts
-
Constants defined inside an interface in XPIDL appear as JavaScript
properties of instances of classes that implement that interface.
Recall that constants must be of type short or long.
It is possible to implement constants of other type (string,
for example)
by holding the value in an attribute of the interface, or returning it
through a method.
| XPIDL code | Example JavaScript |
|---|---|
interface nsIFoo {
const short ONE = 1;
};
|
var myFoo = Components.classes["@mydomain.org/sample/foo;1"].CreateInstance(); var myFoo = myFoo.QueryInteface(Components.interfaces.nsIFoo); print(myFoo.ONE); OR print(Components.interfaces.nsIFoo.ONE); |
-
You should use a return type other than void so that
script writers will be able to use the return value directly.
(In C++ the return value is converted into a trailing out
parameter.)
Any interface that contains native or raw C++ types cannot be made scriptable. The XPIDL compiler will treat it as an error if an interface or method is marked as scriptable and it contains native or raw C++ types.
Individual methods in an interface may be marked as not scriptable by using the [noscript] attribute before the problem method. Methods marked with [noscript] will not be available for use from scripting languages.
| XPIDL code | Comment |
|---|---|
[ptr] native nsNativeType(nsFileSpec);
[scriptable] interface foo {
void BadMethod(in nsNativeType aNativeType);
};
|
Compiler exits with error:
cannot_script.idl:4: Error: methods in [scriptable] interfaces which are non-scriptable because they refer to native types (parameter "aNativeType") must be marked [noscript] |
[ptr] native nsNativeType(nsFileSpec);
[scriptable] interface foo {
[noscript] void BadMethod(in nsNativeType aNativeType);
};
|
C++ header file is generated as normal. BadMethod is not available from JavaScript. |
All strings that are returned through out parameters in C++ must be allocated using the nsIAllocator so that the string's lifetime can be managed by XPConnect. If a string is not allocated with nsIAllocator, then the string will get lost, resulting in a memory leak or crash.
See the XPConnect FAQ item "How do I make 'out string' work right?" for details on how to properly pass strings out of a method.
When choosing method names in your interface, it's best to use the interCaps style - leading lower case, subsequent units within the identifier capitalized. This matches existing JavaScript convention and will look natural to scripters.
The dominant C++ method name convention within Mozilla is to use InterCaps style (leading upper case.) To support this, the xpidl compiler capitalizes method names when generating C++ headers. Even if you're creating IDL for an existing interface with an InterCaps C++ implementation, it's still best if you use interCaps. It'll look familiar to JavaScript authors, and your C++ will still work.
[Rules and Syntax] [Best Practices] [Keywords]
Mike Ang Mike McCabe Last modified: Tue Oct 5 14:45:25 PDT 1999