Loadable service module framework.
More...
|
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) |
|
The service module API presents a means to dynamically load, start, stop, and unload services contained in dynamically loadable object files.
#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
-
name | the bare name of the module file (no extension) |
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] | pServiceName | the name of the service |
[in,out] | pInstance | the 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] | pInstance | the 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] | pInstance | the service instance |
[in] | ArgCount | argument count |
[in] | ppArgv | arguments |
[in] | FdCount | file descriptor count |
[in] | pFds | file 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] | pInstance | the 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] | pInstance | the service instance |
[in] | Status | an NTSTATUS code indicating the result of the command |
[in] | pContext | the user context pointer |
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] | pInstance | the service instance |
[in] | pData | the 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] | pInstance | the 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] | pServiceName | the name of the service |
[in] | pModulePath | the filesystem path of the module object file |
[out] | ppInstance | set 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] | pServiceName | the name of the service |
[in] | Entry | the entry point function |
[out] | ppInstance | set 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] | pInstance | the service instance |
[in] | ArgCount | argument count |
[in] | ppArgs | arguments |
[in] | FdCount | file descriptor count |
[in] | pFds | file descriptors |
[in] | Notify | the callback to invoke when startup completes |
[in] | pContext | a 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] | pInstance | the service instance |
[in] | Notify | the callback to invoke when startup completes |
[in] | pContext | a 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] | pInstance | the service instance |
[in] | Notify | the callback to invoke when startup completes |
[in] | pContext | a 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] | pInstance | the service instance |