meanwhile  1.0.2
Data Structures | Macros | Typedefs | Enumerations
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)   ((struct mwService *) srv)
 Casts a concrete service (such as mwServiceAware) into a mwService. More...
 
#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. More...
 
#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. More...
 
#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...
 

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. More...
 
void mwService_started (struct mwService *service)
 Indicate that a service is started. More...
 
void mwService_stopped (struct mwService *service)
 Indicate that a service is stopped. More...
 
General Services API

These functions provide unified access to the general functions of a client service, with some simple sanity-checking.

void mwService_recvCreate (struct mwService *service, struct mwChannel *channel, struct mwMsgChannelCreate *msg)
 Triggers the recv_create handler on the service. More...
 
void mwService_recvAccept (struct mwService *service, struct mwChannel *channel, struct mwMsgChannelAccept *msg)
 Triggers the recv_accept handler on the service. More...
 
void mwService_recvDestroy (struct mwService *service, struct mwChannel *channel, struct mwMsgChannelDestroy *msg)
 Triggers the recv_destroy handler on the service. More...
 
void mwService_recv (struct mwService *service, struct mwChannel *channel, guint16 msg_type, struct mwOpaque *data)
 Triggers the input handler on the service. More...
 
guint32 mwService_getType (struct mwService *)
 
const char * mwService_getName (struct mwService *)
 
const char * mwService_getDesc (struct mwService *)
 
struct mwSessionmwService_getSession (struct mwService *service)
 
enum mwServiceState mwService_getState (struct mwService *service)
 
void mwService_start (struct mwService *service)
 Triggers the start handler for the service. More...
 
void mwService_stop (struct mwService *service)
 Triggers the stop handler for the service. More...
 
void mwService_free (struct mwService *service)
 Frees memory used by a service. More...
 
void mwService_setClientData (struct mwService *service, gpointer data, GDestroyNotify cleanup)
 Associates client data with service. More...
 
gpointer mwService_getClientData (struct mwService *service)
 Reference associated client data. More...
 
void mwService_removeClientData (struct mwService *service)
 Removes client data from service. More...
 

Macro Definition 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

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
serviceThe 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
servicethe service to initialize
sessionthe service's owning session
service_typethe 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
servicethe service to receive the input
channelthe channel the input was received from
msg_typethe service-dependant message type
datathe message data
void mwService_recvAccept ( struct mwService service,
struct mwChannel channel,
struct mwMsgChannelAccept msg 
)

Triggers the recv_accept handler on the service.

Parameters
servicethe service to handle the message
channelthe channel being accepted
msgthe channel accept message
void mwService_recvCreate ( struct mwService service,
struct mwChannel channel,
struct mwMsgChannelCreate msg 
)

Triggers the recv_create handler on the service.

Parameters
servicethe service to handle the message
channelthe channel being created
msgthe channel create message
void mwService_recvDestroy ( struct mwService service,
struct mwChannel channel,
struct mwMsgChannelDestroy msg 
)

Triggers the recv_destroy handler on the service.

Parameters
servicethe service to handle the message
channelthe channel being destroyed
msgthe 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
serviceThe 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
serviceThe 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.