mw_service.h File Reference

#include "mw_common.h"

Go to the source code of this file.

Data Structures
struct	mwService
	A service is the recipient of sendOnCnl messages sent over channels marked with the corresponding service id. More...

Macros
#define	MW_SERVICE(srv)
	Casts a concrete service (such as mwServiceAware) into a mwService.
#define	MW_SERVICE_IS_DEAD(srvc)
	If a service is STOPPING or STOPPED, it's considered DEAD.
#define	MW_SERVICE_IS_LIVE(srvc)
	If a service is STARTING or STARTED, it's considered LIVE.
#define	MW_SERVICE_IS_STARTED(srvc)
#define	MW_SERVICE_IS_STARTING(srvc)
#define	MW_SERVICE_IS_STATE(srvc, state)
#define	MW_SERVICE_IS_STOPPED(srvc)
#define	MW_SERVICE_IS_STOPPING(srvc)

Typedefs
typedef void(*)	mwService_funcClear(struct mwService *service)
typedef const char *(*)	mwService_funcGetDesc(struct mwService *service)
typedef const char *(*)	mwService_funcGetName(struct mwService *service)
typedef void(*)	mwService_funcRecv(struct mwService *service, struct mwChannel *channel, guint16 msg_type, struct mwOpaque *data)
typedef void(*)	mwService_funcRecvAccept(struct mwService *service, struct mwChannel *channel, struct mwMsgChannelAccept *msg)
typedef void(*)	mwService_funcRecvCreate(struct mwService *service, struct mwChannel *channel, struct mwMsgChannelCreate *msg)
typedef void(*)	mwService_funcRecvDestroy(struct mwService *service, struct mwChannel *channel, struct mwMsgChannelDestroy *msg)
typedef void(*)	mwService_funcStart(struct mwService *service)
typedef void(*)	mwService_funcStop(struct mwService *service)

Enumerations
enum	mwServiceState {   mwServiceState_STOPPED ,   mwServiceState_STOPPING ,   mwServiceState_STARTED ,   mwServiceState_STARTING ,   mwServiceState_ERROR ,   mwServiceState_UNKNOWN }
	State-tracking for a service. More...

Functions
Service Extension API
These functions are for use by service implementations
void	mwService_init (struct mwService *service, struct mwSession *session, guint32 service_type)
	Prepares a newly allocated service for use.
void	mwService_started (struct mwService *service)
	Indicate that a service is started.
void	mwService_stopped (struct mwService *service)
	Indicate that a service is stopped.
General Services API
These functions provide unified access to the general functions of a client service, with some simple sanity-checking.
void	mwService_free (struct mwService *service)
	Frees memory used by a service.
gpointer	mwService_getClientData (struct mwService *service)
	Reference associated client data.
const char *	mwService_getDesc (struct mwService *)
const char *	mwService_getName (struct mwService *)
struct mwSession *	mwService_getSession (struct mwService *service)
enum mwServiceState	mwService_getState (struct mwService *service)
guint32	mwService_getType (struct mwService *)
void	mwService_recv (struct mwService *service, struct mwChannel *channel, guint16 msg_type, struct mwOpaque *data)
	Triggers the input handler on the service.
void	mwService_recvAccept (struct mwService *service, struct mwChannel *channel, struct mwMsgChannelAccept *msg)
	Triggers the recv_accept handler on the service.
void	mwService_recvCreate (struct mwService *service, struct mwChannel *channel, struct mwMsgChannelCreate *msg)
	Triggers the recv_create handler on the service.
void	mwService_recvDestroy (struct mwService *service, struct mwChannel *channel, struct mwMsgChannelDestroy *msg)
	Triggers the recv_destroy handler on the service.
void	mwService_removeClientData (struct mwService *service)
	Removes client data from service.
void	mwService_setClientData (struct mwService *service, gpointer data, GDestroyNotify cleanup)
	Associates client data with service.
void	mwService_start (struct mwService *service)
	Triggers the start handler for the service.
void	mwService_stop (struct mwService *service)
	Triggers the stop handler for the service.

Macro Definition Documentation

MW_SERVICE

#define MW_SERVICE

(

srv

)

Value:

((struct mwService *) srv)

Casts a concrete service (such as mwServiceAware) into a mwService.

MW_SERVICE_IS_DEAD

#define MW_SERVICE_IS_DEAD

(

srvc

)

Value:

(MW_SERVICE_IS_STOPPING(srvc) || MW_SERVICE_IS_STOPPED(srvc))

If a service is STOPPING or STOPPED, it's considered DEAD.

MW_SERVICE_IS_LIVE

#define MW_SERVICE_IS_LIVE

(

srvc

)

Value:

(MW_SERVICE_IS_STARTING(srvc) || MW_SERVICE_IS_STARTED(srvc))

If a service is STARTING or STARTED, it's considered LIVE.

MW_SERVICE_IS_STARTED

#define MW_SERVICE_IS_STARTED

(

srvc

)

Value:

MW_SERVICE_IS_STATE(srvc, mwServiceState_STARTED)

MW_SERVICE_IS_STARTING

#define MW_SERVICE_IS_STARTING

(

srvc

)

Value:

MW_SERVICE_IS_STATE(srvc, mwServiceState_STARTING)

MW_SERVICE_IS_STATE

#define MW_SERVICE_IS_STATE	(		srvc,
			state )

Value:

(mwService_getState(MW_SERVICE(srvc)) == (state))

MW_SERVICE_IS_STOPPED

#define MW_SERVICE_IS_STOPPED

(

srvc

)

Value:

MW_SERVICE_IS_STATE(srvc, mwServiceState_STOPPED)

MW_SERVICE_IS_STOPPING

#define MW_SERVICE_IS_STOPPING

(

srvc

)

Value:

MW_SERVICE_IS_STATE(srvc, mwServiceState_STOPPING)

Typedef Documentation

mwService_funcClear

typedef void(*) mwService_funcClear(struct mwService *service)

mwService_funcGetDesc

typedef const char *(*) mwService_funcGetDesc(struct mwService *service)

mwService_funcGetName

typedef const char *(*) mwService_funcGetName(struct mwService *service)

mwService_funcRecv

typedef void(*) mwService_funcRecv(struct mwService *service, struct mwChannel *channel, guint16 msg_type, struct mwOpaque *data)

mwService_funcRecvAccept

typedef void(*) mwService_funcRecvAccept(struct mwService *service, struct mwChannel *channel, struct mwMsgChannelAccept *msg)

Todo

remove msg and replace with appropriate additional parameters

mwService_funcRecvCreate

typedef void(*) mwService_funcRecvCreate(struct mwService *service, struct mwChannel *channel, struct mwMsgChannelCreate *msg)

Todo

remove msg and replace with appropriate additional parameters

mwService_funcRecvDestroy

typedef void(*) mwService_funcRecvDestroy(struct mwService *service, struct mwChannel *channel, struct mwMsgChannelDestroy *msg)

Todo

remove msg and replace with appropriate additional parameters

mwService_funcStart

typedef void(*) mwService_funcStart(struct mwService *service)

mwService_funcStop

typedef void(*) mwService_funcStop(struct mwService *service)

Enumeration Type Documentation

mwServiceState

enum mwServiceState

State-tracking for a service.

Enumerator
mwServiceState_STOPPED	the service is not active
mwServiceState_STOPPING	the service is shutting down
mwServiceState_STARTED	the service is active
mwServiceState_STARTING	the service is starting up
mwServiceState_ERROR	error in service, shutting down
mwServiceState_UNKNOWN	error determining state

Function Documentation

mwService_free()

void mwService_free

(

struct mwService *

service

)

Frees memory used by a service.

Will trigger the stop handler if the service is STARTED or STARTING. Triggers clear handler to allow cleanup.

Parameters

service

The service to clear and free

References mwService_free().

Referenced by mwService_free().

mwService_getClientData()

gpointer mwService_getClientData

(

struct mwService *

service

)

Reference associated client data.

References mwService_getClientData().

Referenced by mwService_getClientData().

mwService_getDesc()

const char * mwService_getDesc

(

struct mwService *

)

Returns

string short description of the service

References mwService_getDesc().

Referenced by mwService_getDesc().

mwService_getName()

const char * mwService_getName

(

struct mwService *

)

Returns

string short name of the service

References mwService_getName().

Referenced by mwService_getName().

mwService_getSession()

struct mwSession * mwService_getSession

(

struct mwService *

service

)

Returns

the service's session

References mwService_getSession().

Referenced by mwService_getSession().

mwService_getState()

enum mwServiceState mwService_getState

(

struct mwService *

service

)

Returns

the service's state

References mwService_getState().

Referenced by mwService_getState().

mwService_getType()

guint32 mwService_getType

(

struct mwService *

)

Returns

the appropriate type id for the service

References mwService_getType().

Referenced by mwService_getType().

mwService_init()

void mwService_init	(	struct mwService *	service,
		struct mwSession *	session,
		guint32	service_type )

Prepares a newly allocated service for use.

Intended for use by service implementations, rather than by code utilizing a service.

The service state will be initialized to STOPPED.

Parameters

service	the service to initialize
session	the service's owning session
service_type	the service ID number

References mwService_init().

Referenced by mwService_init().

mwService_recv()

void mwService_recv	(	struct mwService *	service,
		struct mwChannel *	channel,
		guint16	msg_type,
		struct mwOpaque *	data )

Triggers the input handler on the service.

Parameters

service	the service to receive the input
channel	the channel the input was received from
msg_type	the service-dependant message type
data	the message data

References mwService_recv().

Referenced by mwService_recv().

mwService_recvAccept()

void mwService_recvAccept	(	struct mwService *	service,
		struct mwChannel *	channel,
		struct mwMsgChannelAccept *	msg )

Triggers the recv_accept handler on the service.

Parameters

service	the service to handle the message
channel	the channel being accepted
msg	the channel accept message

References mwService_recvAccept().

Referenced by mwService_recvAccept().

mwService_recvCreate()

void mwService_recvCreate	(	struct mwService *	service,
		struct mwChannel *	channel,
		struct mwMsgChannelCreate *	msg )

Triggers the recv_create handler on the service.

Parameters

service	the service to handle the message
channel	the channel being created
msg	the channel create message

References mwService_recvCreate().

Referenced by mwService_recvCreate().

mwService_recvDestroy()

void mwService_recvDestroy	(	struct mwService *	service,
		struct mwChannel *	channel,
		struct mwMsgChannelDestroy *	msg )

Triggers the recv_destroy handler on the service.

Parameters

service	the service to handle the message
channel	the channel being destroyed
msg	the channel destroy message

References mwService_recvDestroy().

Referenced by mwService_recvDestroy().

mwService_removeClientData()

void mwService_removeClientData

(

struct mwService *

service

)

Removes client data from service.

If there is a cleanup function, it will be called.

References mwService_removeClientData().

Referenced by mwService_removeClientData().

mwService_setClientData()

void mwService_setClientData	(	struct mwService *	service,
		gpointer	data,
		GDestroyNotify	cleanup )

Associates client data with service.

If there is existing data, it will not have its cleanup function called. Client data is not for use by service implementations. Rather, it is for use by client code which may later make use of those service implementations.

References mwService_setClientData().

Referenced by mwService_setClientData().

mwService_start()

void mwService_start

(

struct mwService *

service

)

Triggers the start handler for the service.

Normally called from the session upon receipt of a service available message. Service implementations should use this handler to open any necessary channels, etc. Checks that the service is STOPPED, or returns.

Parameters

service

The service to start

References mwService_start().

Referenced by mwService_start().

mwService_started()

void mwService_started

(

struct mwService *

service

)

Indicate that a service is started.

To be used by service implementations when the service is fully started.

References mwService_started().

Referenced by mwService_started().

mwService_stop()

void mwService_stop

(

struct mwService *

service

)

Triggers the stop handler for the service.

Normally called from the session before closing down the connection. Checks that the service is STARTED or STARTING, or returns

Parameters

service

The service to stop

References mwService_stop().

Referenced by mwService_stop().

mwService_stopped()

void mwService_stopped

(

struct mwService *

service

)

Indicate that a service is stopped.

To be used by service implementations when the service is fully stopped.

References mwService_stopped().

Referenced by mwService_stopped().