Main Page | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

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...

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 *)
mwSessionmwService_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.

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.

Defines

#define MW_SERVICE(srv)   ((struct mwService *) srv)
 Casts a concrete service (such as mwServiceAware) into a mwService.
#define MW_SERVICE_IS_DEAD(srvc)   (MW_SERVICE_IS_STOPPING(srvc) || MW_SERVICE_IS_STOPPED(srvc))
 If a service is STOPPING or STOPPED, it's considered DEAD.
#define MW_SERVICE_IS_LIVE(srvc)   (MW_SERVICE_IS_STARTING(srvc) || MW_SERVICE_IS_STARTED(srvc))
 If a service is STARTING or STARTED, it's considered LIVE.
#define MW_SERVICE_IS_STARTED(srvc)   MW_SERVICE_IS_STATE(srvc, mwServiceState_STARTED)
#define MW_SERVICE_IS_STARTING(srvc)   MW_SERVICE_IS_STATE(srvc, mwServiceState_STARTING)
#define MW_SERVICE_IS_STATE(srvc, state)   (mwService_getState(MW_SERVICE(srvc)) == (state))
#define MW_SERVICE_IS_STOPPED(srvc)   MW_SERVICE_IS_STATE(srvc, mwServiceState_STOPPED)
#define MW_SERVICE_IS_STOPPING(srvc)   MW_SERVICE_IS_STATE(srvc, mwServiceState_STOPPING)

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...

Variables

mwService_funcClear clear
 The service's cleanup handler.
GDestroyNotify client_cleanup
 Optional client data cleanup function.
gpointer client_data
 Optional client data, not for use by service implementations.
mwService_funcGetDesc get_desc
mwService_funcGetName get_name
mwService_funcRecv recv
 The service's input handler.
mwService_funcRecvAccept recv_accept
 The service's channel accept handler.
mwService_funcRecvCreate recv_create
 The service's channel create handler.
mwService_funcRecvDestroy recv_destroy
 The service's channel destroy handler.
mwSessionsession
 session this service is attached to.
mwService_funcStart start
 The service's start handler.
enum mwServiceState state
 the state of this service.
mwService_funcStop stop
 The service's stop handler.


Define Documentation

#define MW_SERVICE srv   )     ((struct mwService *) srv)
 

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

#define MW_SERVICE_IS_DEAD srvc   )     (MW_SERVICE_IS_STOPPING(srvc) || MW_SERVICE_IS_STOPPED(srvc))
 

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

#define MW_SERVICE_IS_LIVE srvc   )     (MW_SERVICE_IS_STARTING(srvc) || MW_SERVICE_IS_STARTED(srvc))
 

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

#define MW_SERVICE_IS_STARTED srvc   )     MW_SERVICE_IS_STATE(srvc, mwServiceState_STARTED)
 

#define MW_SERVICE_IS_STARTING srvc   )     MW_SERVICE_IS_STATE(srvc, mwServiceState_STARTING)
 

#define MW_SERVICE_IS_STATE srvc,
state   )     (mwService_getState(MW_SERVICE(srvc)) == (state))
 

#define MW_SERVICE_IS_STOPPED srvc   )     MW_SERVICE_IS_STATE(srvc, mwServiceState_STOPPED)
 

#define MW_SERVICE_IS_STOPPING srvc   )     MW_SERVICE_IS_STATE(srvc, mwServiceState_STOPPING)
 


Typedef Documentation

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)
 

Todo:
remove msg and replace with appropriate additional parameters

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

Todo:
remove msg and replace with appropriate additional parameters

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

Todo:
remove msg and replace with appropriate additional parameters

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

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


Enumeration Type Documentation

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

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

gpointer mwService_getClientData struct mwService service  ) 
 

Reference associated client data.

const char* mwService_getDesc struct mwService  ) 
 

Returns:
string short description of the service

const char* mwService_getName struct mwService  ) 
 

Returns:
string short name of the service

struct mwSession* mwService_getSession struct mwService service  ) 
 

Returns:
the service's session

enum mwServiceState mwService_getState struct mwService service  ) 
 

Returns:
the service's state

guint32 mwService_getType struct mwService  ) 
 

Returns:
the appropriate type id for the service

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

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

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

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

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

void mwService_removeClientData struct mwService service  ) 
 

Removes client data from service.

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

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.

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

void mwService_started struct mwService service  ) 
 

Indicate that a service is started.

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

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

void mwService_stopped struct mwService service  ) 
 

Indicate that a service is stopped.

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


Variable Documentation

mwService_funcClear clear
 

The service's cleanup handler.

Service implementations should presume that mwService::stop will be called first. The clear handler is not for shutting down channels or generating non-cleanup side-effects, it is only for handling tear-down of the service, and will only be called once for any instance.

GDestroyNotify client_cleanup
 

Optional client data cleanup function.

Called with client_data from mwService_free

gpointer client_data
 

Optional client data, not for use by service implementations.

mwService_funcGetDesc get_desc
 

Returns:
string short description of the service

mwService_funcGetName get_name
 

Returns:
string short name of the service

mwService_funcRecv recv
 

The service's input handler.

Called when the session receives data on a channel belonging to this service

mwService_funcRecvAccept recv_accept
 

The service's channel accept handler.

Called when the session receives a channel accept message for a channel with a service matching this service's type.

mwService_funcRecvCreate recv_create
 

The service's channel create handler.

Called when the session receives a channel create message with a service matching this service's type.

mwService_funcRecvDestroy recv_destroy
 

The service's channel destroy handler.

Called when the session receives a channel destroy message for a channel with a service matching this service's type.

struct mwSession* session
 

session this service is attached to.

mwService_funcStart start
 

The service's start handler.

Called upon the receipt of a service available message.

enum mwServiceState state
 

the state of this service.

Determines whether or not the session should call the start function upon receipt of a service available message. Should not be set or checked by hand.

mwService_funcStop stop
 

The service's stop handler.

Called when the session is shutting down, or when the service is free'd.


Generated on Tue Oct 10 20:21:16 2006 for meanwhile by  doxygen 1.4.4