Likewise Service Manager
Client API

Client API. More...

Data Structures

struct  PLW_SERVICE_INFO
 Service information. More...
 
struct  PLW_SERVICE_STATUS
 Service status. More...
 

Typedefs

typedef struct _LW_SERVICE_HANDLE * LW_SERVICE_HANDLE
 Opaque service handle. More...
 

Enumerations

enum  LW_SM_LOG_LEVEL {
  LW_SM_LOG_LEVEL_DEFAULT,
  LW_SM_LOG_LEVEL_ALWAYS,
  LW_SM_LOG_LEVEL_ERROR,
  LW_SM_LOG_LEVEL_WARNING,
  LW_SM_LOG_LEVEL_INFO,
  LW_SM_LOG_LEVEL_VERBOSE,
  LW_SM_LOG_LEVEL_DEBUG,
  LW_SM_LOG_LEVEL_TRACE
}
 Log level. More...
 
enum  LW_SM_LOGGER_TYPE {
  LW_SM_LOGGER_DEFAULT,
  LW_SM_LOGGER_NONE,
  LW_SM_LOGGER_FILE,
  LW_SM_LOGGER_SYSLOG
}
 Logger type. More...
 
enum  LW_SERVICE_STATE {
  LW_SERVICE_STATE_RUNNING,
  LW_SERVICE_STATE_STOPPED,
  LW_SERVICE_STATE_STARTING,
  LW_SERVICE_STATE_STOPPING,
  LW_SERVICE_STATE_PAUSED,
  LW_SERVICE_STATE_DEAD
}
 State of a service. More...
 
enum  LW_SERVICE_TYPE {
  LW_SERVICE_TYPE_LEGACY_EXECUTABLE,
  LW_SERVICE_TYPE_EXECUTABLE,
  LW_SERVICE_TYPE_MODULE,
  LW_SERVICE_TYPE_DRIVER,
  LW_SERVICE_TYPE_STUB
}
 Service type. More...
 
enum  LW_SERVICE_HOME {
  LW_SERVICE_HOME_STANDALONE,
  LW_SERVICE_HOME_CONTAINER,
  LW_SERVICE_HOME_IO_MANAGER,
  LW_SERVICE_HOME_SERVICE_MANAGER
}
 Service home. More...
 
enum  LW_SERVICE_INFO_MASK {
  LW_SERVICE_INFO_MASK_NAME,
  LW_SERVICE_INFO_MASK_DESCRIPTION,
  LW_SERVICE_INFO_MASK_TYPE,
  LW_SERVICE_INFO_MASK_PATH,
  LW_SERVICE_INFO_MASK_ARGS,
  LW_SERVICE_INFO_MASK_ENVIRONMENT,
  LW_SERVICE_INFO_MASK_DEPENDENCIES,
  LW_SERVICE_INFO_MASK_AUTOSTART,
  LW_SERVICE_INFO_MASK_FD_LIMIT,
  LW_SERVICE_INFO_MASK_GROUP,
  LW_SERVICE_INFO_MASK_LOG = 0x400,
  LW_SERVICE_INFO_MASK_ALL
}
 Service info mask. More...
 
enum  LW_SM_GLOBAL_SETTING {
  LW_SM_GLOBAL_SETTING_NONE,
  LW_SM_GLOBAL_SETTING_WATCHDOG
}
 

Functions

DWORD LwSmAcquireServiceHandle (LW_PCWSTR pwszServiceName, PLW_SERVICE_HANDLE phHandle)
 Acquire service handle. More...
 
DWORD LwSmReleaseServiceHandle (LW_SERVICE_HANDLE hHandle)
 Release a service handle. More...
 
DWORD LwSmEnumerateServices (PWSTR **pppwszServiceNames)
 Enumerate available services. More...
 
VOID LwSmFreeServiceNameList (PWSTR *ppwszServiceNames)
 Free service name list. More...
 
DWORD LwSmAddService (PCLW_SERVICE_INFO pServiceInfo, PLW_SERVICE_HANDLE phHandle)
 Add new service. More...
 
DWORD LwSmRemoveService (LW_SERVICE_HANDLE hHandle)
 Remove an existing service. More...
 
DWORD LwSmUpdateServiceInfo (LW_SERVICE_HANDLE hHandle, PCLW_SERVICE_INFO pServiceInfo, LW_SERVICE_INFO_MASK mask)
 Update service information. More...
 
DWORD LwSmStartService (LW_SERVICE_HANDLE hHandle)
 Start a service. More...
 
DWORD LwSmStopService (LW_SERVICE_HANDLE hHandle)
 Stop a service. More...
 
DWORD LwSmQueryServiceStatus (LW_SERVICE_HANDLE hHandle, PLW_SERVICE_STATUS pStatus)
 Get service status. More...
 
DWORD LwSmWaitService (LW_SERVICE_HANDLE hHandle, LW_SERVICE_STATE currentState, PLW_SERVICE_STATE pNewState)
 Wait for service state change. More...
 
DWORD LwSmRefreshService (LW_SERVICE_HANDLE hHandle)
 Refresh service. More...
 
DWORD LwSmSetServiceLogTarget (LW_SERVICE_HANDLE hHandle, LW_PCSTR pFacility, LW_SM_LOGGER_TYPE type, PCSTR pTarget)
 Sets log target for a service. More...
 
DWORD LwSmSetServiceLogLevel (LW_SERVICE_HANDLE hHandle, LW_PCSTR pFacility, LW_SM_LOG_LEVEL level)
 Set maximum log level for a service. More...
 
DWORD LwSmGetServiceLogState (LW_SERVICE_HANDLE hHandle, LW_PCSTR pFacility, PLW_SM_LOGGER_TYPE pType, LW_PSTR *ppTarget, PLW_SM_LOG_LEVEL pLevel)
 Get current logging state for a service. More...
 
VOID LwSmFreeLogTarget (LW_PSTR pTarget)
 Free logging target. More...
 
DWORD LwSmEnumerateServiceLogFacilities (LW_SERVICE_HANDLE hHandle, LW_PWSTR **pppFacilities)
 Enumerate logging facilities for a service. More...
 
VOID LwSmFreeLogFacilityList (LW_PWSTR *ppFacilities)
 Free log facility list. More...
 
DWORD LwSmQueryServiceInfo (LW_SERVICE_HANDLE hHandle, PLW_SERVICE_INFO *ppInfo)
 Get service info. More...
 
DWORD LwSmQueryServiceDependencyClosure (LW_SERVICE_HANDLE hHandle, PWSTR **pppwszServiceList)
 Get recursive dependency list. More...
 
DWORD LwSmQueryServiceReverseDependencyClosure (LW_SERVICE_HANDLE hHandle, PWSTR **pppwszServiceList)
 Get recursive reverse dependency list. More...
 
VOID LwSmFreeServiceInfo (PLW_SERVICE_INFO pInfo)
 Free service info structure. More...
 
DWORD LwSmRefresh (VOID)
 Refresh service manager. More...
 
DWORD LwSmShutdown (VOID)
 Shutdown. More...
 
DWORD LwSmSetGlobal (LW_IN LW_SM_GLOBAL_SETTING Setting,...)
 Change global setting. More...
 
DWORD LwSmGetGlobal (LW_IN LW_SM_GLOBAL_SETTING Setting,...)
 Get global setting. More...
 
VOID LwSmFreeGlobal (LW_IN LW_SM_GLOBAL_SETTING Setting,...)
 Free global setting value. More...
 

Detailed Description

This module contains the client-side API used to query and control services in the Likewise Service Manager (lwsmd)

Typedef Documentation

typedef struct _LW_SERVICE_HANDLE* LW_SERVICE_HANDLE

A handle to a particular service that can be used to query or perform operations upon it.

Enumeration Type Documentation

Describes the level of a log message in terms of importance.

Enumerator
LW_SM_LOG_LEVEL_DEFAULT 

Indicates the default log level.

LW_SM_LOG_LEVEL_ALWAYS 

Message that should always be logged.

LW_SM_LOG_LEVEL_ERROR 

Message that indicates an error condition.

LW_SM_LOG_LEVEL_WARNING 

Message that indicates a warning condition.

LW_SM_LOG_LEVEL_INFO 

Message that informs the user of a normal but significant condition or event.

LW_SM_LOG_LEVEL_VERBOSE 

Message that informs the user of a normal and common event.

LW_SM_LOG_LEVEL_DEBUG 

Message that is only of interest when attempting to debug improper program behavior.

LW_SM_LOG_LEVEL_TRACE 

Message that tracks low-level program execution flow.

Indicates the type of logging target

Enumerator
LW_SM_LOGGER_DEFAULT 

Log to the default target.

LW_SM_LOGGER_NONE 

Do not log.

LW_SM_LOGGER_FILE 

Log to file.

LW_SM_LOGGER_SYSLOG 

Log to syslog.

Represents the state of a service (running, stopped, etc.)

Enumerator
LW_SERVICE_STATE_RUNNING 

Service is running.

LW_SERVICE_STATE_STOPPED 

Service is stopped.

LW_SERVICE_STATE_STARTING 

Service is starting.

LW_SERVICE_STATE_STOPPING 

Service is stopping.

LW_SERVICE_STATE_PAUSED 

Service is paused.

LW_SERVICE_STATE_DEAD 

Service is pining for the fjords.

Represents the type of a service

Enumerator
LW_SERVICE_TYPE_LEGACY_EXECUTABLE 

Service is a legacy executable.

LW_SERVICE_TYPE_EXECUTABLE 

Service is an lwsm-aware executable.

LW_SERVICE_TYPE_MODULE 

Service is a module for a container.

LW_SERVICE_TYPE_DRIVER 

Service is a driver.

LW_SERVICE_TYPE_STUB 

Service is a dummy stub.

Denotes the location of a running service.

Enumerator
LW_SERVICE_HOME_STANDALONE 

Service is running in a standalone process.

LW_SERVICE_HOME_CONTAINER 

Service is running in a service container.

LW_SERVICE_HOME_IO_MANAGER 

Service is running in the IO manager.

LW_SERVICE_HOME_SERVICE_MANAGER 

Service is running directly in the service manager.

A bitmask which indicates which fields to update in an LwSmUpdateServiceInfo() call.

Enumerator
LW_SERVICE_INFO_MASK_NAME 

Update name.

LW_SERVICE_INFO_MASK_DESCRIPTION 

Update description.

LW_SERVICE_INFO_MASK_TYPE 

Update type.

LW_SERVICE_INFO_MASK_PATH 

Update path.

LW_SERVICE_INFO_MASK_ARGS 

Update arguments.

LW_SERVICE_INFO_MASK_ENVIRONMENT 

Update environment variables.

LW_SERVICE_INFO_MASK_DEPENDENCIES 

Update dependencies.

LW_SERVICE_INFO_MASK_AUTOSTART 

Update autostart flag.

LW_SERVICE_INFO_MASK_FD_LIMIT 

Update fd limit.

LW_SERVICE_INFO_MASK_GROUP 

Update service group name.

LW_SERVICE_INFO_MASK_LOG 

Update service log settings.

LW_SERVICE_INFO_MASK_ALL 

Update all flags.

Enumerator
LW_SM_GLOBAL_SETTING_NONE 

No setting.

LW_SM_GLOBAL_SETTING_WATCHDOG 

Control service watchdog.

(BOOLEAN) Turns service watchdog on or off globally

Function Documentation

DWORD LwSmAcquireServiceHandle ( LW_PCWSTR  pwszServiceName,
PLW_SERVICE_HANDLE  phHandle 
)

Gets a handle to a known service by name

Parameters
[in]pwszServiceNamethe name of the service
[out]phHandlea service handle
Return values
LW_ERROR_SUCCESSsuccess
LW_ERROR_NO_SUCH_SERVICEno service with the specified name exists
DWORD LwSmReleaseServiceHandle ( LW_SERVICE_HANDLE  hHandle)

Releases a handle previously acquired with LwSmAcquireServiceHandle().

Parameters
[in]hHandlethe service handle
Return values
LW_ERROR_SUCCESSsuccess
DWORD LwSmEnumerateServices ( PWSTR **  pppwszServiceNames)

Returns a NULL-terminated list of strings containing the names of all known services. The list should be freed with LwSmFreeServiceNameList() when done.

Parameters
[out]pppwszServiceNamesthe returned list of services
Return values
LW_ERROR_SUCCESSsuccess
VOID LwSmFreeServiceNameList ( PWSTR *  ppwszServiceNames)

Frees a service name list as returned by e.g. LwSmEnumerateServices()

Parameters
[in,out]ppwszServiceNamesthe list of services
DWORD LwSmAddService ( PCLW_SERVICE_INFO  pServiceInfo,
PLW_SERVICE_HANDLE  phHandle 
)

Adds a new service to the service manager described by the provided service info structure and returns a handle to it.

Parameters
[in]pServiceInfoa service info structure describing the new service
[out]phHandlethe created service
DWORD LwSmRemoveService ( LW_SERVICE_HANDLE  hHandle)

Removes an existing service from the service manager. The service will not actually be removed until the last handle to it is released with LwSmReleaseServiceHandle().

Parameters
[in]hHandlethe service handle
Return values
LW_ERROR_SUCCESSsuccess
DWORD LwSmUpdateServiceInfo ( LW_SERVICE_HANDLE  hHandle,
PCLW_SERVICE_INFO  pServiceInfo,
LW_SERVICE_INFO_MASK  mask 
)

Updates the basic information for a service.

Parameters
[in]hHandlethe service handle
[in]pServiceInfoservice information
[in]maska bitmask describing which information fields to update
Return values
LW_ERROR_SUCCESSsuccess
LW_ERROR_ACCESS_DENIEDthe caller does not have permission to update the service
DWORD LwSmStartService ( LW_SERVICE_HANDLE  hHandle)

Starts the service represented by the given service handle. If the service is already started, this function trivially succeeds. If the service is not started, it will attempt to start it and wait for it finish starting. If the service is in the process of starting, it will wait for it to finish starting.

Parameters
[in]hHandlethe service handle
Return values
LW_ERROR_SUCCESSsuccess
LW_ERROR_SERVICE_UNRESPONSIVEthe service did not respond to requests to start
LW_ERROR_SERVICE_DEPENDENCY_UNMETthe service depends on another service which is not running
LW_ERROR_INVALID_SERVICE_TRANSITIONthe service cannot be started in its present state
DWORD LwSmStopService ( LW_SERVICE_HANDLE  hHandle)

Stops the service represented by the given service handle. If the service is already stopped, this function trivially succeeds. If the service is not stopped, it will attempt to stop it and wait for it finish stopping. If the service is in the process of stopping, it will wait for it to finish stopping.

Parameters
[in]hHandlethe service handle
Return values
LW_ERROR_SUCCESSsuccess
LW_ERROR_SERVICE_UNRESPONSIVEthe service did not respond to requests to stop
LW_ERROR_DEPENDENT_SERVICE_STILL_RUNNINGthe service cannot be stopped as another running service depends on it
LW_ERROR_INVALID_SERVICE_TRANSITIONthe service cannot be started in its present state
DWORD LwSmQueryServiceStatus ( LW_SERVICE_HANDLE  hHandle,
PLW_SERVICE_STATUS  pStatus 
)

Gets the current status of the service represented by the given service handle.

Parameters
[in]hHandlethe service handle
[out]pStatusthe status of the service
Return values
LW_ERROR_SUCCESSsuccess
DWORD LwSmWaitService ( LW_SERVICE_HANDLE  hHandle,
LW_SERVICE_STATE  currentState,
PLW_SERVICE_STATE  pNewState 
)

Waits for the given service's state to change. The last known state of the service must be specified as a parameter, and the new state will be returned when a change occurs.

Note
This function requires the last known state of the service to be passed in to guard against a race condition in which the service changes state after its status is queried but before this function is called. Passing in the last known state guarantees that this function will return immediately if the service has changed state since the last query.
Parameters
[in]hHandlethe service handle
[in]currentStatethe last known state of the service
[out]pNewStatethe new state of the service
DWORD LwSmRefreshService ( LW_SERVICE_HANDLE  hHandle)

Refreshes the service represented by the given service handle, which typically entails it reloading its configuration.

Parameters
[in]hHandlethe service handle
Return values
LW_ERROR_SUCCESSsuccess
DWORD LwSmSetServiceLogTarget ( LW_SERVICE_HANDLE  hHandle,
LW_PCSTR  pFacility,
LW_SM_LOGGER_TYPE  type,
PCSTR  pTarget 
)

Sets the log target for a service. If the service is running in a container, all services in the same container will be affected.

Parameters
[in]hHandlethe service handle, or NULL to specify lwsmd itself
[in]pFacilitythe facility to redirect, or NULL to set the default log target
[in]typethe type of logging target
[in]pTargetthe logging target, or NULL for target types that don't require it
Return values
ERROR_SUCCESSsuccess
ERROR_NOT_SUPPORTEDthe specified service does not support setting log targets
DWORD LwSmSetServiceLogLevel ( LW_SERVICE_HANDLE  hHandle,
LW_PCSTR  pFacility,
LW_SM_LOG_LEVEL  level 
)

Sets the maximum log level for a service. If the service is running in a container, all services in the same container will be affected.

Parameters
[in]hHandlethe service handle, or NULL to specify lwsmd itself
[in]pFacilitythe facility to set the level for, or NULL to set the default log level
[in]levelthe maximum log level to set
Return values
ERROR_SUCCESSsuccess
ERROR_NOT_SUPPORTEDthe specified service does not support setting log targets
DWORD LwSmGetServiceLogState ( LW_SERVICE_HANDLE  hHandle,
LW_PCSTR  pFacility,
PLW_SM_LOGGER_TYPE  pType,
LW_PSTR *  ppTarget,
PLW_SM_LOG_LEVEL  pLevel 
)

Gets the current logging target and maximum log level for a service. If the service is running in a container, the returned values apply to all services in the same container. The returned logging target string can be freed with LwSmFreeLogTarget().

Parameters
[in]hHandlethe service handle, or NULL to specify lwsmd itself
[in]pFacilitythe facility to get state for, or NULL for the default state
[out]pTypeset to the logging target type
[out]ppTargetset to the logging target if applicable or NULL otherwise
[out]pLevelset to the maximum log level
Return values
ERROR_SUCCESS
ERROR_NOT_SUPPORTEDthe specified service does not support getting log state
VOID LwSmFreeLogTarget ( LW_PSTR  pTarget)

Frees a logging target string returned by a previous call to LwSmGetServiceLogState().

Parameters
[in,out]pTarget
DWORD LwSmEnumerateServiceLogFacilities ( LW_SERVICE_HANDLE  hHandle,
LW_PWSTR **  pppFacilities 
)

Enumerates all logging facilities for a service that have a non-default configuration.

Parameters
[in]hHandlethe service handle, or NULL to specify lwsmd itself
[out]pppFacilitiesset to the list of facilities
Return values
ERROR_SUCCESS
ERROR_NOT_SUPPORTEDthe specified service does not support getting log state
VOID LwSmFreeLogFacilityList ( LW_PWSTR *  ppFacilities)

Frees a list of logging facilities returned by LwSmEnumerateServiceLogFacilities().

DWORD LwSmQueryServiceInfo ( LW_SERVICE_HANDLE  hHandle,
PLW_SERVICE_INFO *  ppInfo 
)

Gets the service info structore of the service represented by the given service handle. The structure should be freed with LwSmFreeServiceInfo() when done.

Parameters
[in]hHandlethe service handle
[out]ppInfothe info structure for the service
Return values
LW_ERROR_SUCCESSsuccess
DWORD LwSmQueryServiceDependencyClosure ( LW_SERVICE_HANDLE  hHandle,
PWSTR **  pppwszServiceList 
)

Gets a list of all recursive dependencies of the service represented by the given service handle – that is, all services the given service depends on directly or indirectly. The entries in the list will be in the order in which they would need to be started in order to start the given service. The list should be freed with LwSmFreeServiceNameList() when done.

Parameters
[in]hHandlethe service handle
[out]pppwszServiceListthe service dependency list
Return values
LW_ERROR_SUCCESSsuccess
DWORD LwSmQueryServiceReverseDependencyClosure ( LW_SERVICE_HANDLE  hHandle,
PWSTR **  pppwszServiceList 
)

Gets a list of all recursive reverse dependencies of the service represented by the given service handle – that is, all services which depend on the given service directly or indirectly. The entries in the list will be in the order in which they would need to be stopped in order to stop the given service. The list should be freed with LwSmFreeServiceNameList() when done.

Parameters
[in]hHandlethe service handle
[out]pppwszServiceListthe service reverse dependency list
Return values
LW_ERROR_SUCCESSsuccess
VOID LwSmFreeServiceInfo ( PLW_SERVICE_INFO  pInfo)

Frees a service info structure as returned by e.g. LwSmQueryServiceInfo()

Parameters
[in,out]pInfothe service info structure to free
DWORD LwSmRefresh ( VOID  )

Causes the service manager to reread its own configuration. To refresh the configuration of a particular service, use LwSmRefreshService().

Return values
LW_ERROR_SUCCESSsuccess
DWORD LwSmShutdown ( VOID  )

Causes the service manager to shut down completely.

Return values
LW_ERROR_SUCCESSsuccess
DWORD LwSmSetGlobal ( LW_IN LW_SM_GLOBAL_SETTING  Setting,
  ... 
)

Changes a global setting. See the description of each global setting for the type of parameters to pass as the trailing arguments.

Parameters
[in]Settingthe setting to change
[in]...value or values for the given setting
Return values
#ERROR_SUCCESSsuccess
#ERROR_INVALID_PARAMETERinvalid setting or value
DWORD LwSmGetGlobal ( LW_IN LW_SM_GLOBAL_SETTING  Setting,
  ... 
)

Gets the value of a global setting. The trailing parameters should be out pointers to the appropriate types listed in the description of the setting to change.

Parameters
[in]Settingthe setting to get
[out]...set to the value or values for the given setting
VOID LwSmFreeGlobal ( LW_IN LW_SM_GLOBAL_SETTING  Setting,
  ... 
)

Frees the value of a global setting previously returned by LwSmGetGlobal().

Parameters
[in]Settingthe setting associated with the value to free
[in,out]...the value or values to free