mozdev.org

plXPCOM   

Home | Todo List | Mailing List | Installation | Source Code | Bugs | Documentation

XPCOM::Components - Perl interface to the XPCOM Component Manager.

NAME

XPCOM::Components - Perl interface to the XPCOM Component Manager.


SYNOPSIS

  use XPCOM::Components;

  $aClass = $Components::classes{'@mydomain.com/some-component;1'};
  $iFace = $aClass->QueryInterface($Components::interfaces{'someIFace'});
  $iFace->someFunction();


DESCRIPTION

This module provides access to the XPCOM Component Manager and Service Manager from Perl. From this module a perl script can create an instance of any scriptable XPCOM component. The typical method of obtaining a new component is to retrieve an instance of it from the hash %Components::classes. For example:

  $aClass = $Components::classes{'@mydomain.com/some-component;1'};

You can also use the older method, which is to use the Components::Classes() function (Note the difference in case):

  $aClass = Components::Classes('@mydomain.com/some-component;1');

Once this call is made, you are still not ready to use the functions of the 
component. You must first call QueryInterface() on the new object to get an 
instance of the object implementing a particular interface. This is because 
a given object can support multiple interfaces (in fact, they all do, since 
every component supports nsISupports as well as at least one derived 
interface). Getting an interface is done thusly:
  $anInterface = 
      $aClass->QueryInterface($Components::interfaces{"anInterfaceName"});

Following this call, you can now use $anInterface to call methods of the requested interface. If QueryInterface() fails (e.g. the class doesn't support that interface), it will return undef. Note that you obtain an interface ID from the %Components::interfaces hash. This returns the interface ID object for the interface. The QueryInterface() method still supports the older call method of simply providing an interface name as a string, but this method is deprecated and its use in new code should be discouraged.

The XPCOM::Components module has other functions as well, which we'll now discuss.

  $aClass = Components::ClassesByID("aClassID");

This is the same as Classes() with the exception being that it accepts the string for of the classes CID instead of its contract ID.

  $aService Components::GetService("contractID", 
                                   $Components::interface{"anInterfaceName"});

This function obtains a new instance of a service component from the Service Manager. It takes two string arguments. This first is the service's contract ID, the second is the interface name of the service. Because you are providing both the contract ID and interface, you do not need to call QueryInterface on the returned object, it is usable right away. For example, the following code shows how to obtain an instance of the Viper Socket Service:

  $sockService = Components::GetService(
                                  '@jumpline.com/network/socket-service;1',
                                  $Components::interfaces{"vpISocketService"});
  $aSocket = $sockService->getOpenSocket(1, "jumpline.com", 80);

The following method provides a means of obtaining the interface ID of an object:

  $iid = $Components::interfaces{'someIFaceName'};

This is the 'proper' means of refering to interfaces for methods such as QueryInterface().

This package also provides serveral methods for dealing with error checking and XPCOM method result codes. While typically invisible to scripting languages, every XPCOM method returns a status code. Whenever you invoke a method of an XPCOM object, this result is stored in the variable $XPCOM::Components::returnCode. XPCOM has a very complex error report code organization (error codes are unsigned longs). To make things easy, the following function will return whether or not a return code is a success or error code:

  Components::isSuccessCode($retval)

If the return code is a success code this function returns true, otherwise it returns false.

In addition, several common response codes are represented as constants under the XPCOM::Components::results namespace. For example, the following code demonstrates the proper means of creating an object and querying the interface with proper error checking:

  my $class = Components::Classes('@somedomain.com/some-class;1');
  if(!defined($class)) { print "Error\n"; exit; }
  my $obj = $class->QueryInterface($Components::interfaces{'someIFace'});
  if(!Components::isSuccessCode($Components::returnCode)) {
    # Checks if it's a no interface error
    if($Components::returnCode  == Components::results::NS_ERROR_NO_INTERFACE) {
      print "No such interface.\n";
    } else {
      print "An error occured in QueryInterface()\n";
    }
    exit;
  }
  ...

The module also implements a function called Constructor(), which is 
currently too annoying to recommend its use as you must provide it with the 
string form of the CID and IID of the component you wish to construct, which 
are typically not known to a script writer. This will be rectified at a later 
date.


AUTHOR

Matt Kennedy <matt@jumpline.com>


SEE ALSO

perl(1) XPCOM::nsISupports

The plxpcom project can be contacted through the mailing list or the member list.
Copyright © 2000-2014. All rights reserved. Terms of Use & Privacy Policy.