The oskit_services COM interface allows components to lookup and rendezvous with an arbitrary “service” using the interface ID (IID) of the desired interface. More than one interface supporting a particular IID can be registered. One particular implementation of a services registry is the global registry object, which can be used by any library or component. The oskit_services COM interface inherits from oskit_iunknown, and has the following additional methods:
#include <oskit/com/services.h>
OSKIT_COMDECL oskit_services_addservice(oskit_services_t *s, const struct oskit_guid *iid, void *interface);
Register a COM interface in the services registry. An additional reference on the interface is taken. More than one interface may be registered for a particular IID. Attempts to register an interface that is already registered will succeed, although the registry will remain unchanged and no additional references will be taken.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/com/services.h>
OSKIT_COMDECL oskit_services_remservice(oskit_services_t *s, const struct oskit_guid *iid, void *interface);
Unregister a COM interface that has been previously registered in the services registry. The reference on the interface that was taken in oskit_services_addservice is released.
Returns 0 on success, or OSKIT_E_INVALIDARG if the specified IID and COM interface is not in the registry.
#include <oskit/com/services.h>
OSKIT_COMDECL oskit_services_lookup(oskit_services_t *s, const struct oskit_guid *iid, [out] void ***out_interface_array);
Look up the set of interfaces that have been registered with a particular IID, returning an array of COM interfaces. The client is responsible for releasing the references on the interfaces, and deallocating the array (with free). By default, the first interface registered is the first interface placed in the array.
Returns the number of COM interfaces found, or 0 if there were no matches.
#include <oskit/com/services.h>
OSKIT_COMDECL oskit_services_lookup(oskit_services_t *s, const struct oskit_guid *iid, [out] void **out_interface);
Look up the first COM interface that has been registered with a particular IID. The client is responsible for releasing the reference on the interface.
Always returns 0, setting out_interface to NULL if there was no match.
#include <oskit/com/services.h> #include <oskit/com/mem.h>
oskit_error_t oskit_services_create(struct oskit_mem *memobject, [out] oskit_services_t **out_interface);
Create a new oskit_services object. An optional oskit_mem COM object, which if provided, is used to satisfy memory requests inside the services object. If a memory object is not provided, the global registry is consulted for the default memory object.
The reason for the providing a memory object is so that the internal implementation does not need to depend on malloc for creating its internal data structures. This makes is possible to use services objects in different environments, such as device driver libraries. Note that the array returned from oskit_services_lookup is allocated with malloc, and should be released with free
Returns 0 on success, or OSKIT_E_OUTOFMEMORY if the services object could not be created because of a memory shortage.
The Global Registry is simply an instantiation of an oskit_services COM object, that can be accessed through a set of well known entrypoints. The global registry is created by the Client OS library when the kernel is initialized. The global registry supports the following interface functions, which chain directly to their oskit_services interface counterparts. Consult the interface descriptions in Section 5.1 for more details.
#include <oskit/com/services.h>
oskit_error_t oskit_register(const struct oskit_guid *iid, void *interface);
Register a COM interface in the global registry using oskit_services_addservice.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/com/services.h>
oskit_error_t oskit_unregister(const struct oskit_guid *iid, void *interface);
Unregister a COM interface using oskit_services_remservice.
Returns 0 on success, or OSKIT_E_INVALIDARG if the specified IID and COM interface is not in the registry.
#include <oskit/com/services.h>
oskit_error_t oskit_lookup(const struct oskit_guid *iid, [out] void ***out_interface_array);
Look up the set of interfaces using oskit_services_lookup.
Returns the number of COM interfaces found, or 0 if there were no matches.
#include <oskit/com/services.h>
oskit_error_t oskit_lookup_first(const struct oskit_guid *iid, [out] void **out_interface);
Look up the first COM interface using oskit_services_lookup_first.
Always returns 0, setting out_interface to NULL if there was no match.