Likewise Base Runtime Library
Service modules

Loadable service module framework. More...

Data Structures

struct  PLW_SVCM_MODULE
 Service module function table. More...
 

Macros

#define LW_RTL_SVCM_ENTRY_POINT_NAME(name)
 Service module entry point name. More...
 

Typedefs

typedef struct _LW_SVCM_INSTANCE LW_SVCM_INSTANCE
 Service instance. More...
 
typedef struct _LW_SVCM_INSTANCE * PLW_SVCM_INSTANCE
 
typedef LW_NTSTATUS(* LW_SVCM_INIT_FUNCTION )(LW_IN LW_PCWSTR pServiceName, LW_IN LW_OUT PLW_SVCM_INSTANCE pInstance)
 Service init function. More...
 
typedef LW_NTSTATUS(* LW_SVCM_COMMAND_FUNCTION )(LW_IN PLW_SVCM_INSTANCE pInstance)
 Generic service command function. More...
 
typedef LW_NTSTATUS(* LW_SVCM_START_FUNCTION )(LW_IN PLW_SVCM_INSTANCE pInstance, LW_IN LW_ULONG ArgCount, LW_IN LW_PWSTR *ppArgs, LW_IN LW_ULONG FdCount, LW_IN int *pFds)
 Service start function. More...
 
typedef VOID(* LW_SVCM_DESTROY_FUNCTION )(LW_IN LW_OUT PLW_SVCM_INSTANCE pInstance)
 Service destroy function. More...
 
typedef PLW_SVCM_MODULE(* LW_SVCM_MODULE_ENTRY_FUNCTION )(LW_VOID)
 Service module entry point. More...
 
typedef VOID(* LW_SVCM_NOTIFY_FUNCTION )(LW_IN PLW_SVCM_INSTANCE pInstance, LW_IN LW_NTSTATUS Status, LW_IN LW_PVOID pContext)
 Service command completion function. More...
 

Functions

VOID LwRtlSvcmSetData (LW_IN LW_OUT PLW_SVCM_INSTANCE pInstance, LW_IN LW_PVOID pData)
 Set arbitrary data on service instance. More...
 
PVOID LwRtlSvcmGetData (PLW_SVCM_INSTANCE pInstance)
 Get arbitrary data on service instance. More...
 
LW_NTSTATUS LwRtlSvcmLoadModule (LW_IN LW_PCWSTR pServiceName, LW_IN LW_PCWSTR pModulePath, LW_OUT PLW_SVCM_INSTANCE *ppInstance)
 Load a service module. More...
 
LW_NTSTATUS LwRtlSvcmLoadEmbedded (LW_IN LW_PCWSTR pServiceName, LW_IN LW_SVCM_MODULE_ENTRY_FUNCTION Entry, LW_OUT PLW_SVCM_INSTANCE *ppInstance)
 Load an embedded service. More...
 
LW_NTSTATUS LwRtlSvcmStart (LW_IN PLW_SVCM_INSTANCE pInstance, LW_IN LW_ULONG ArgCount, LW_IN LW_PWSTR *ppArgs, LW_IN LW_ULONG FdCount, LW_IN int *pFds, LW_IN LW_OPTIONAL LW_SVCM_NOTIFY_FUNCTION Notify, LW_IN LW_OPTIONAL LW_PVOID pContext)
 Start a service. More...
 
LW_NTSTATUS LwRtlSvcmStop (LW_IN PLW_SVCM_INSTANCE pInstance, LW_IN LW_OPTIONAL LW_SVCM_NOTIFY_FUNCTION Notify, LW_IN LW_OPTIONAL LW_PVOID pContext)
 Stop a service. More...
 
LW_NTSTATUS LwRtlSvcmRefresh (LW_IN PLW_SVCM_INSTANCE pInstance, LW_IN LW_OPTIONAL LW_SVCM_NOTIFY_FUNCTION Notify, LW_IN LW_OPTIONAL LW_PVOID pContext)
 Refresh service configuration. More...
 
VOID LwRtlSvcmUnload (LW_IN LW_OUT PLW_SVCM_INSTANCE pInstance)
 Unload a service. More...
 
VOID LwRtlSvcmFreePool (VOID)
 

Detailed Description

The service module API presents a means to dynamically load, start, stop, and unload services contained in dynamically loadable object files.

Macro Definition Documentation

#define LW_RTL_SVCM_ENTRY_POINT_NAME (   name)

The entry point function of a service module must have a name derived from the use of this macro.

Parameters
namethe bare name of the module file (no extension)

Typedef Documentation

typedef struct _LW_SVCM_INSTANCE LW_SVCM_INSTANCE

An opaque structure that represents an instance of a service loaded from a service module.

typedef LW_NTSTATUS(* LW_SVCM_INIT_FUNCTION)(LW_IN LW_PCWSTR pServiceName, LW_IN LW_OUT PLW_SVCM_INSTANCE pInstance)

Initializes an instance of of the specified service. Arbitrary data can be attached to the instance structure with LwRtlSvcmSetData().

Parameters
[in]pServiceNamethe name of the service
[in,out]pInstancethe new service instance
Returns
an NTSTATUS code
typedef LW_NTSTATUS(* LW_SVCM_COMMAND_FUNCTION)(LW_IN PLW_SVCM_INSTANCE pInstance)

Generic function type for issuing a no-argument command to a service.

Parameters
[in]pInstancethe service instance
Returns
an NTSTATUS code
typedef LW_NTSTATUS(* LW_SVCM_START_FUNCTION)(LW_IN PLW_SVCM_INSTANCE pInstance, LW_IN LW_ULONG ArgCount, LW_IN LW_PWSTR *ppArgs, LW_IN LW_ULONG FdCount, LW_IN int *pFds)

Instructs the given service to start. This function may safely block until the service is completely ready.

Parameters
[in]pInstancethe service instance
[in]ArgCountargument count
[in]ppArgvarguments
[in]FdCountfile descriptor count
[in]pFdsfile descriptors
Returns
an NTSTATUS code
typedef VOID(* LW_SVCM_DESTROY_FUNCTION)(LW_IN LW_OUT PLW_SVCM_INSTANCE pInstance)

Destroys any state associated with the given service instance.

Parameters
[in]pInstancethe service instance
typedef PLW_SVCM_MODULE(* LW_SVCM_MODULE_ENTRY_FUNCTION)(LW_VOID)

Returns the service module function table for a service module. An function with this prototype named LW_RTL_SVCM_ENTRY_POINT_NAME should be exported by the service module's object file.

typedef VOID(* LW_SVCM_NOTIFY_FUNCTION)(LW_IN PLW_SVCM_INSTANCE pInstance, LW_IN LW_NTSTATUS Status, LW_IN LW_PVOID pContext)

A callback provided by the loader of a service that is invoked when a command completes.

Parameters
[in]pInstancethe service instance
[in]Statusan NTSTATUS code indicating the result of the command
[in]pContextthe user context pointer

Function Documentation

VOID LwRtlSvcmSetData ( LW_IN LW_OUT PLW_SVCM_INSTANCE  pInstance,
LW_IN LW_PVOID  pData 
)

Sets an arbitrary data pointer on the service instance that can be retrieved with LwRtlSvcmGetData(). This function should only be used by the service module itself and not by the loader.

Parameters
[in,out]pInstancethe service instance
[in]pDatathe data pointer to set
PVOID LwRtlSvcmGetData ( PLW_SVCM_INSTANCE  pInstance)

Gets the arbitrary data pointer on the service previously set by LwRtlSvcmSetData(). This function should only be used by the service module itself and not by the loader.

Parameters
[in]pInstancethe service instance
Returns
the data pointer
LW_NTSTATUS LwRtlSvcmLoadModule ( LW_IN LW_PCWSTR  pServiceName,
LW_IN LW_PCWSTR  pModulePath,
LW_OUT PLW_SVCM_INSTANCE *  ppInstance 
)

Loads the service with the given name from the module file at the specified path.

Parameters
[in]pServiceNamethe name of the service
[in]pModulePaththe filesystem path of the module object file
[out]ppInstanceset to the created service instance
Returns
an NTSTATUS code
LW_NTSTATUS LwRtlSvcmLoadEmbedded ( LW_IN LW_PCWSTR  pServiceName,
LW_IN LW_SVCM_MODULE_ENTRY_FUNCTION  Entry,
LW_OUT PLW_SVCM_INSTANCE *  ppInstance 
)

Loads the service with the given name directly from the specified module entry point. This allows services to be compiled directly into a program and then loaded.

Parameters
[in]pServiceNamethe name of the service
[in]Entrythe entry point function
[out]ppInstanceset to the created service instance
Returns
an NTSTATUS code
LW_NTSTATUS LwRtlSvcmStart ( LW_IN PLW_SVCM_INSTANCE  pInstance,
LW_IN LW_ULONG  ArgCount,
LW_IN LW_PWSTR *  ppArgs,
LW_IN LW_ULONG  FdCount,
LW_IN int *  pFds,
LW_IN LW_OPTIONAL LW_SVCM_NOTIFY_FUNCTION  Notify,
LW_IN LW_OPTIONAL LW_PVOID  pContext 
)

Instructs the given service instance to start. This function will return immediately – the provided notify callback will be invoked when the service has completed starting.

Parameters
[in]pInstancethe service instance
[in]ArgCountargument count
[in]ppArgsarguments
[in]FdCountfile descriptor count
[in]pFdsfile descriptors
[in]Notifythe callback to invoke when startup completes
[in]pContexta context pointer to pass to the notify function
Returns
an NTSTATUS code
LW_NTSTATUS LwRtlSvcmStop ( LW_IN PLW_SVCM_INSTANCE  pInstance,
LW_IN LW_OPTIONAL LW_SVCM_NOTIFY_FUNCTION  Notify,
LW_IN LW_OPTIONAL LW_PVOID  pContext 
)

Instructs the given service instance to stop. This function will return immediately – the provided notify callback will be invoked when the service has completed stopping.

Parameters
[in]pInstancethe service instance
[in]Notifythe callback to invoke when startup completes
[in]pContexta context pointer to pass to the notify function
Returns
an NTSTATUS code
LW_NTSTATUS LwRtlSvcmRefresh ( LW_IN PLW_SVCM_INSTANCE  pInstance,
LW_IN LW_OPTIONAL LW_SVCM_NOTIFY_FUNCTION  Notify,
LW_IN LW_OPTIONAL LW_PVOID  pContext 
)

Instructs the given service instance to refresh its configuration. This function will return immediately – the provided notify callback will be invoked when the service has completed refreshing.

Parameters
[in]pInstancethe service instance
[in]Notifythe callback to invoke when startup completes
[in]pContexta context pointer to pass to the notify function
Returns
an NTSTATUS code
VOID LwRtlSvcmUnload ( LW_IN LW_OUT PLW_SVCM_INSTANCE  pInstance)

Completely unloads the given service instance. It is up to the caller to first ensure that the service is stopped, or the behavior of this function is undefined.

Parameters
[in,out]pInstancethe service instance