services.h File Reference

OS service and daemon management utilities. More...

#include "gate/system/gate_system_api.h"
#include "gate/gatetypes.h"
#include "gate/strings.h"
#include "gate/arrays.h"

Data Structures
struct	gate_service_class
	Service entry data record. More...
struct	gate_service_config_class
	Service configuration data record. More...

Macros
#define	GATE_SERVICE_STATE_UNKNOWN   0
#define	GATE_SERVICE_STATE_STOPPED   1
#define	GATE_SERVICE_STATE_RUNNING   2
#define	GATE_SERVICE_STATE_ERROR   3
#define	GATE_SERVICE_STATE_PAUSED   4
#define	GATE_SERVICE_STATE_STARTING   5
#define	GATE_SERVICE_STATE_STOPPING   6
#define	GATE_SERVICE_FLAG_AUTOSTART   1
#define	GATE_SERVICE_FLAG_DISABLED   2

Typedefs
typedef struct gate_service_class	gate_service_t
	Service entry data record.
typedef struct gate_service_config_class	gate_service_config_t
	Service configuration data record.
typedef gate_bool_t(*	gate_service_enum_callback_t) (gate_service_t const *service, void *user_param)
	function callback type to receive enumerated services
typedef void(*	gate_service_message_callback_t) (gate_string_t const *message, void *user_param)
	function callback that receives progress messages during operation

Functions
GATE_SYSTEM_API gate_result_t	gate_services_enum (gate_service_enum_callback_t callback, void *user_param)
	Enumerates all available service and invokes a callback for each entry.
GATE_SYSTEM_API gate_result_t	gate_service_start (gate_string_t const *name, gate_service_message_callback_t msg_callback, void *user_param)
	Starts a service identified by its name.
GATE_SYSTEM_API gate_result_t	gate_service_stop (gate_string_t const *name, gate_uint32_t wait_timeout, gate_bool_t force, gate_service_message_callback_t msg_callback, void *user_param)
	Stops a running service identified by its name.
GATE_SYSTEM_API gate_result_t	gate_service_get_config (gate_string_t const *name, gate_service_config_t *config)
	Retrieves a configuration record from a service.
GATE_SYSTEM_API gate_result_t	gate_service_get_status (gate_string_t const *name, gate_enumint_t *state, gate_string_t *process_id)
	Retrieves a current status of a service.
GATE_SYSTEM_API gate_result_t	gate_service_register (gate_string_t const *name, gate_string_t const *command, gate_string_t const *descr, gate_uint32_t flags, gate_string_t const *dependencies, gate_service_message_callback_t msg_callback, void *user_param)
	Registers a new service process in the system's service manager.
GATE_SYSTEM_API gate_result_t	gate_service_unregister (gate_string_t const *name, gate_service_message_callback_t msg_callback, void *user_param)
	Unregisters a registered service.
GATE_SYSTEM_API char const *	gate_service_print_state (gate_enumint_t state)
	Returns a human readable string representing a GATE_SERVICE_STATE_* value.

Detailed Description

OS service and daemon management utilities.

Macro Definition Documentation

GATE_SERVICE_STATE_UNKNOWN

#define GATE_SERVICE_STATE_UNKNOWN   0

state of service is unknown

GATE_SERVICE_STATE_STOPPED

#define GATE_SERVICE_STATE_STOPPED   1

service is NOT running (offline)

GATE_SERVICE_STATE_RUNNING

#define GATE_SERVICE_STATE_RUNNING   2

service is running (online)

GATE_SERVICE_STATE_ERROR

#define GATE_SERVICE_STATE_ERROR   3

service is in error state and not functional

GATE_SERVICE_STATE_PAUSED

#define GATE_SERVICE_STATE_PAUSED   4

service was started and is currently paused

GATE_SERVICE_STATE_STARTING

#define GATE_SERVICE_STATE_STARTING   5

service is starting but not yet ready to be used

GATE_SERVICE_STATE_STOPPING

#define GATE_SERVICE_STATE_STOPPING   6

service is running but currently shuting down

GATE_SERVICE_FLAG_AUTOSTART

#define GATE_SERVICE_FLAG_AUTOSTART   1

service is automatically started

GATE_SERVICE_FLAG_DISABLED

#define GATE_SERVICE_FLAG_DISABLED   2

service is disabled and cannot be started

Function Documentation

gate_services_enum()

GATE_SYSTEM_API gate_result_t gate_services_enum	(	gate_service_enum_callback_t	callback,
		void *	user_param )

Enumerates all available service and invokes a callback for each entry.

Parameters

[in]	callback	Callback to be called for each service entry
[in]	user_param	User parameter attached to each callback call

Returns

GATE_RESULT_* result code

gate_service_start()

GATE_SYSTEM_API gate_result_t gate_service_start	(	gate_string_t const *	name,
		gate_service_message_callback_t	msg_callback,
		void *	user_param )

Starts a service identified by its name.

Parameters

[in]	name	Name of services to be started
[in]	msg_callback	Optional callback for startup-messages during service startup
[in]	user_param	Parameter attached to each msg_callback call

Returns

GATE_RESULT_* result code

gate_service_stop()

GATE_SYSTEM_API gate_result_t gate_service_stop	(	gate_string_t const *	name,
		gate_uint32_t	wait_timeout,
		gate_bool_t	force,
		gate_service_message_callback_t	msg_callback,
		void *	user_param )

Stops a running service identified by its name.

Parameters

[in]	name	Name of services to be stopped
[in]	msg_callback	Optional callback for shutdown-messages during service startup
[in]	user_param	Parameter attached to each msg_callback call

Returns

GATE_RESULT_* result code

gate_service_get_config()

GATE_SYSTEM_API gate_result_t gate_service_get_config	(	gate_string_t const *	name,
		gate_service_config_t *	config )

Retrieves a configuration record from a service.

Parameters

[in]	name	Name of services to be accessed
[out]	config	Pointer to configuration object to be initialized with service data

Returns

GATE_RESULT_* result code

gate_service_get_status()

GATE_SYSTEM_API gate_result_t gate_service_get_status	(	gate_string_t const *	name,
		gate_enumint_t *	state,
		gate_string_t *	process_id )

Retrieves a current status of a service.

Parameters

[in]	name	Name of services to be accessed
[out]	state	Pointer to integer to be initialized with GATE_SERVICE_STATE_* value
[out]	process_id	Optional pointer to string to be initialized with serialized process identifier

Returns

GATE_RESULT_* result code

gate_service_register()

GATE_SYSTEM_API gate_result_t gate_service_register	(	gate_string_t const *	name,
		gate_string_t const *	command,
		gate_string_t const *	descr,
		gate_uint32_t	flags,
		gate_string_t const *	dependencies,
		gate_service_message_callback_t	msg_callback,
		void *	user_param )

Registers a new service process in the system's service manager.

Parameters

[in]	name	Name of new service
[in]	command	Command line string required to start the service
[in]	descr	Optional description of the service
[in]	flags	Additional service related flags
[in]	dependencies	comma separated list of service names that need to start before the new service
[in]	msg_callback	Optional callback function that receives status messages during registration process
[in]	user_param	User parameter attached to each call of msg_callback

Returns

GATE_RESULT_* result code

gate_service_unregister()

GATE_SYSTEM_API gate_result_t gate_service_unregister	(	gate_string_t const *	name,
		gate_service_message_callback_t	msg_callback,
		void *	user_param )

Unregisters a registered service.

Parameters

[in]	name	Name of new service
[in]	msg_callback	Optional callback function that receives status messages during unregistration process
[in]	user_param	User parameter attached to each call of msg_callback

Returns

GATE_RESULT_* result code