xpcom/components/nsIServiceManager.idlScriptable
This interface provides a means to obtain global services in an application. The service manager depends on the repository to find and instantiate factories to obtain services.
Inherits from: nsISupports Last changed in Gecko 1.0

Method overview

void getService(in nsCIDRef aClass, in nsIIDRef aIID, [iid_is(aIID),retval] out nsQIResult result);
void getServiceByContractID(in string aContractID, in nsIIDRef aIID, [iid_is(aIID),retval] out nsQIResult result);
boolean isServiceInstantiated(in nsCIDRef aClass, in nsIIDRef aIID);
boolean isServiceInstantiatedByContractID(in string aContractID, in nsIIDRef aIID);

Methods

getService()

This method returns a reference to a particular XPCOM service given the ClassID of the service. Unlike createInstance, this will always return the same object each time it is called with the same arguments.

void getService(
  in nsCIDRef aClass,
  in nsIIDRef aIID,
  [iid_is(aIID),retval] out nsQIResult result
);
Parameters
aClass
The ClassID of the service that is being requested.
aIID
The interface type to be returned.
result
The resulting interface pointer.
Exceptions thrown
NS_ERROR_FACTORY_NOT_REGISTERED
Indicates that the specified class is not registered.

getServiceByContractID()

This method returns a reference to a particular XPCOM service given the ContractID of the service.

void getServiceByContractID(
  in string aContractID,
  in nsIIDRef aIID,
  [iid_is(aIID),retval] out nsQIResult result
);
Parameters
aContractID
The ContractID of the service that is being requested.
aIID
The interface type to be returned.
result
The resulting interface pointer.
Exceptions thrown
NS_ERROR_FACTORY_NOT_REGISTERED
Indicates that the specified class is not registered.

isServiceInstantiated()

This method tests whether or not a XPCOM service, identified by ClassID, has been instantiated.

boolean isServiceInstantiated(
  in nsCIDRef aClass,
  in nsIIDRef aIID
);
Parameters
aClass
The ClassID of the service that is being tested.
aIID
The interface type to be tested.
Return value

true if the service has already been created.

Exceptions thrown
NS_ERROR_SERVICE_NOT_AVAILABLE
Indicates that the service hasn't been instantiated.
NS_NOINTERFACE
Indicates that the IID given isn't supported.

isServiceInstantiatedByContractID()

This method tests whether or not a XPCOM service, identified by ContractID, has been instantiated.

boolean isServiceInstantiatedByContractID(
  in string aContractID,
  in nsIIDRef aIID
);
Parameters
aContractID
The ContractID of the service that is being tested.
aIID
The interface type to be tested.
Return value

true if the service has already been created.

Exceptions thrown
NS_ERROR_SERVICE_NOT_AVAILABLE
Indicates that the service hasn't been instantiated.
NS_NOINTERFACE
Indicates that the IID given isn't supported.

Remarks

The service manager depends on the repository to find and instantiate factories to obtain services.

Because services are instantiated lazily, methods are provided to test whether or not a service has already been instantiated.

Users of the service manager must first obtain a pointer to the global service manager by calling NS_GetServiceManager. After that, they can request specific services by calling getService(). When they are finished they should call nsISupports.release() on the service as they would with any interface pointer. In some language bindings, such as JavaScript, this step is unnecessary. And, moreover such languages typically offer more convenient mechanisms to acquire references to XPCOM services and components.

A user of a service may keep references to services until application shutdown.

This interface was frozen for Gecko 1.0. See bug 99147 for details. From Gecko 2.0 interfaces are no longer frozen.

See also