View source for Researching XPIDL and IDL Technologies

== Introduction == 
XPIDL stands for XP Interface Description Language.  It is a specification for XPCOM which is a cross platform adapter description language.   An adapter description language is used to describe   an adapter which unrelated with its machine language.  The description of the adapter can use specialized tools to handle automatic generation of language that is unrelated to the adapter's specifications.   Typically XPIDL is frequently used to generate C++ header files and typelib information.

== Language ==

=== Interfaces ===
An interface is declared with the interface keyword, 
and the simplest possible interface is a declaration without any methods or attributes.
  interface nsToolbar {
  };

To specify an interface's parent, follow the interface name with a colon and the parent name 
 interface nsIToolbar : nsIParent {
 };

=== Methods ===
An interface can have both methods and attributes.  Attributes are properties of interface objects that can be read and optionally set.  The following example 
-	Attributes,  properties of interface objects, can be read and optionally set. 
-	This is an example of 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. 

In this example many parameters of different types and in an out specifications are seen

 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);
 };

Attributes can be made read-only, by placing the read-only keyword infront of the the definition  
 interface nsIThing {
   readonly attribute string lookButDontTouch;
 };
 C++ get and set methods for attributes are automatically declared for attributes in the   
 interface.

=== Compiler ===
The compiler capitalizes method names when generating C++ headers.
It supports  existing C++ convention in Mozilla, used the InterCaps method naming style. The method name used in XPIDL will appear with the same capitalization to JavaScript, so the best practice is to match JavaScript convention by declaring attributes and method names in InterCaps.

===  Built In Types ===
 Type                    C++ 

 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*

==== Native Types ====

      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);
Reference and pointer types can be defined by combining [ref] or [ptr] with native languages
 XPIDL Code                                                Generated C++
 [ref] native nsNativeFileRef(nsFileSpec);                 /* starting interface:  foo */
 [ptr] native nsNativeFilePtr(nsFileSpec);                 class foo {
                                                            public:
                                                            /* void openByRef (in nsNativeFileRef aFileSpecRef); */
                                                            NS_IMETHOD OpenByRef(nsFileSpec & aFileSpecRef) = 0;
                                                            /* void openByPtr (in nsNativeFilePtr aFileSpecPtr); */ 
                                                            NS_IMETHOD OpenByPtr(nsFileSpec * aFileSpecPtr) = 0;
                                                           };    
 interface foo {
   void openByRef(in nsNativeFileRef aFileSpecRef);
   void openByPtr(in nsNativeFilePtr aFileSpecPtr);
 };      

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

=== Include Terminology ===
 To referencing interfaces defined in other files, you must type #include "filename.idl".
 In XPIDL, #include only includes the file once, so the #include statement does not need the ifdefs which will be required for the    
 the C preprocessor.

=== Enumerations and Constants  ===
C-style enumerations are not supported in XPIDL because the size of enums can be compiler specific. XPIDL alternatively supports defining constants that appear in the C++ and JavaScript mappings.  They must be of type short or long and have to be present inside an interface declaration.
Other types are not supported because they do not map into all languages or have memory management issues. To define a constant that is neither short or long, write a method that returns the value, or include the value in 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

== NewsGroups ==

[http://groups.google.com/group/netscape.public.mozilla.xpcom?lnk=sg netscape.public.mozilla.xpcom]

[http://groups.google.com/group/netscape.public.mozilla.os2?lnk=sg netscape.public.mozilla.os2] 

These groups typically have topics that relate to XPIDL.

== Resources  ==

[http://www.mozilla.org/scriptable/faq.html Frequently Asked Questions about XPConnect and XPIDL]

[http://64.233.179.104/translate_c?hl=en&sl=zh-CN&u=http://developer.mozilla.org/cn/docs/XPIDL&prev=/search%3Fq%3DXPIDL%2B%2Bwikipedia%26hl%3Den%26lr%3D%26sa%3DGXPIDL Documentation at Mozilla Development Centre]

[http://www.mozilla.org/scriptable/xpidl/idl-authors-guide/rules.html#interfaces Rules And Syntax]