XPCOM Ruby Language Binding

XPCOM Ruby Language Binding

All API and Language binding described in this documents are subject to change. Pending API changes are filed as bug reports in rbXPCOM's bug tracking system.

Binding described in this section are applied to both using and implementing XPCOM objects.

Interface Refrection

An idl interface is mapped to a Ruby module. XPCOM.interface method provides access to these modules. The IID of the interface can be obtained from the module by iid method.


nsIRegistory = XPCOM.interface("nsIRegistry")

iid = XPCOM::ID.new("{5D41A440-8E37-11d2-8059-00600811A9C3}")

p iid == nsIRegistory.iid                    #=> true
      
# XPCOM.interface acccept IID, too.
p nsIRegistory.equal?(XPCOM.interface(iid))  #=> true
     

The module provides the constants defined in the interface.


XPCOM.interface("nsIRegistory")::Common
     

Parameter Mapping

out and inout

Since Ruby does not have the concept of out parameter, in rbXPCOM, values should be returned via out params are returned as return value of the method. If a method has multiple out parameters, they are returned in an array.


# PRInt16 AddPRInt16( in PRInt16 a,
#                     in PRInt16 b,
#                     inout PRInt16 c, 
#                     out PRInt16 neg);

ret, c, neg = test.AddPRInt16(a, b, c)
      

Parameter passing and returning follow below rules:

  • in parameters are passed as arguments.

  • out parameters are not included in the arguments list. The values are returned from the method.

  • inout are passed like in, and returned like out.

  • When multiple values are returned, the retval of the method comes first, followed by other out params in the order they appear in the idl.

One more example.


# void EchoInterfaceIsPtr(in nsIIDPtr idin,
#                         [iid_is(idin)] in nsQIResult ii,
#                         out nsIIDPtr idout,
#                         [iid_is(idout), retval] out nsQIResult io);

io, idout = test.EchoInterfaceIsPtr(idin, ii)
      

size_is parameter

In xpidl, size_is attribute is used to specify the size of array or non-zero terminated string(wstring). In Ruby, explicitly passing or receiving the size of these objects are redundant, because objects know their size. To remove this redundancy, rbXPCOM hides the size parameters from Ruby code.


# void EchoArray1( in PRUint32 i_size, 
#                  [array, size_is(i_size)] in PRInt16 i,
#                  out PRUint32 o_size,
#                  [array, size_is(o_size)] out PRInt16 o);

o = test.EchoArray1(i)
      

If the size parameter is passed to a method without accompanying sized object, the size parameter appears in the argument list. Following method illustrates this coner case.


# void Foo( in PRUint32 size, [size_is(size)]out string str);

str = test.Foo(size)
      

Data Convertion

Table 1. Data Type Conversion

XPTTypeDescriptor Tagstype in Ruby
TD_INT8Integer
TD_INT16Integer
TD_INT32Integer
TD_INT64Integer
TD_UINT8Integer
TD_UINT16Integer
TD_UINT32Integer
TD_UINT64Integer
TD_FLOATFloat
TD_DOUBLEFloat
TD_BOOLboolean
TD_CHARInteger
TD_WCHARInteger
TD_VOID-
TD_PNSIIDXPCOM::ID
TD_DOMSTRINGString
TD_PSTRINGString
TD_PWSTRINGString
TD_INTERFACE_TYPEobject
TD_INTERFACE_IS_TYPEobject
TD_ARRAYArray
TD_PSTRING_SIZE_ISString
TD_PWSTRING_SIZE_ISString