mw_channel.h File Reference

#include <time.h>
#include "mw_common.h"

Go to the source code of this file.

Defines
#define	MW_MASTER_CHANNEL_ID   0x00000000
	special ID indicating the master channel
#define	mwChannel_idIsIncoming(id)   (! mwChannel_idIsOutgoing(id))
	non-zero if a channel id appears to be that of an incoming channel
#define	mwChannel_idIsOutgoing(id)   (! (0x80000000 & (id)))
	non-zero if a channel id appears to be that of an outgoing channel
#define	mwChannel_isIncoming(chan)   mwChannel_idIsIncoming(mwChannel_getId(chan))
	non-zero if a channel appears to be an incoming channel
#define	mwChannel_isOutgoing(chan)   mwChannel_idIsOutgoing(mwChannel_getId(chan))
	non-zero if a channel appears to be an outgoing channel
#define	mwChannel_isState(chan, state)   (mwChannel_getState(chan) == (state))
Enumerations
enum	mwChannelState {   mwChannel_NEW,   mwChannel_INIT,   mwChannel_WAIT,   mwChannel_OPEN,   mwChannel_DESTROY,   mwChannel_ERROR,   mwChannel_UNKNOWN }
	channel status More...
enum	mwChannelStatField {   mwChannelStat_MSG_SENT,   mwChannelStat_MSG_RECV,   mwChannelStat_U_BYTES_SENT,   mwChannelStat_U_BYTES_RECV,   mwChannelStat_OPENED_AT,   mwChannelStat_CLOSED_AT }
	channel statistic fields. More...
Functions
int	mwChannel_accept (struct mwChannel *chan)
	Formally accept an incoming channel.
void	mwChannel_addSupportedCipherInstance (struct mwChannel *chan, struct mwCipherInstance *ci)
	add a cipher instance to a channel's list of supported ciphers.
int	mwChannel_create (struct mwChannel *chan)
	Formally open a channel.
int	mwChannel_destroy (struct mwChannel *chan, guint32 reason, struct mwOpaque *data)
	Destroy a channel.
mwChannel *	mwChannel_find (struct mwChannelSet *cs, guint32 chan)
	Obtain a reference to a channel by its id.
mwOpaque *	mwChannel_getAddtlAccept (struct mwChannel *)
	direct reference to the accept addtl information for a channel
mwOpaque *	mwChannel_getAddtlCreate (struct mwChannel *)
	direct reference to the create addtl information for a channel
guint32	mwChannel_getId (struct mwChannel *)
	get the ID for a channel.
guint32	mwChannel_getOptions (struct mwChannel *chan)
guint32	mwChannel_getProtoType (struct mwChannel *chan)
guint32	mwChannel_getProtoVer (struct mwChannel *chan)
mwService *	mwChannel_getService (struct mwChannel *)
	get the service for a channel.
gpointer	mwChannel_getServiceData (struct mwChannel *chan)
	get service-specific data.
guint32	mwChannel_getServiceId (struct mwChannel *)
	get the ID of the service for a channel.
mwSession *	mwChannel_getSession (struct mwChannel *)
	get the session for a channel.
enum mwChannelState	mwChannel_getState (struct mwChannel *)
	get the state of a channel
gpointer	mwChannel_getStatistic (struct mwChannel *chan, enum mwChannelStatField stat)
	obtain the value for a statistic field as a gpointer
GList *	mwChannel_getSupportedCipherInstances (struct mwChannel *chan)
	the list of supported ciphers for a channel.
mwLoginInfo *	mwChannel_getUser (struct mwChannel *chan)
	User at the other end of the channel.
mwChannel *	mwChannel_newIncoming (struct mwChannelSet *, guint32 id)
	Create an incoming channel with the given channel id.
mwChannel *	mwChannel_newOutgoing (struct mwChannelSet *)
	Create an outgoing channel.
void	mwChannel_populateSupportedCipherInstances (struct mwChannel *chan)
	automatically adds instances of all ciphers in the session to the list of supported ciphers for a channel
void	mwChannel_recv (struct mwChannel *chan, struct mwMsgChannelSend *msg)
	Feed data into a channel.
void	mwChannel_recvAccept (struct mwChannel *chan, struct mwMsgChannelAccept *msg)
void	mwChannel_recvCreate (struct mwChannel *chan, struct mwMsgChannelCreate *msg)
void	mwChannel_recvDestroy (struct mwChannel *chan, struct mwMsgChannelDestroy *msg)
void	mwChannel_removeServiceData (struct mwChannel *chan)
void	mwChannel_selectCipherInstance (struct mwChannel *chan, struct mwCipherInstance *ci)
	select a cipher instance for a channel.
int	mwChannel_send (struct mwChannel *chan, guint32 msg_type, struct mwOpaque *msg)
	Compose a send-on-channel message, encrypt it as per the channel's specification, and send it.
int	mwChannel_sendEncrypted (struct mwChannel *chan, guint32 msg_type, struct mwOpaque *msg, gboolean encrypt)
	Compose a send-on-channel message, and if encrypt is TRUE, encrypt it as per the channel's specification, and send it.
void	mwChannel_setOptions (struct mwChannel *chan, guint32 options)
void	mwChannel_setProtoType (struct mwChannel *chan, guint32 proto_type)
void	mwChannel_setProtoVer (struct mwChannel *chan, guint32 proto_ver)
void	mwChannel_setService (struct mwChannel *chan, struct mwService *srvc)
	associate a channel with an owning service
void	mwChannel_setServiceData (struct mwChannel *chan, gpointer data, GDestroyNotify clean)
	set service-specific data.
void	mwChannelSet_free (struct mwChannelSet *)
	Clear and deallocate a channel set.
mwChannelSet *	mwChannelSet_new (struct mwSession *)
	Allocate and initialize a channel set for a session.

---

Define Documentation

#define MW_MASTER_CHANNEL_ID   0x00000000

special ID indicating the master channel

#define mwChannel_idIsIncoming (  id   )     (! mwChannel_idIsOutgoing(id))

non-zero if a channel id appears to be that of an incoming channel

#define mwChannel_idIsOutgoing (  id   )     (! (0x80000000 & (id)))

non-zero if a channel id appears to be that of an outgoing channel

#define mwChannel_isIncoming (  chan   )     mwChannel_idIsIncoming(mwChannel_getId(chan))

non-zero if a channel appears to be an incoming channel

#define mwChannel_isOutgoing (  chan   )     mwChannel_idIsOutgoing(mwChannel_getId(chan))

non-zero if a channel appears to be an outgoing channel

#define mwChannel_isState (  chan, state   )     (mwChannel_getState(chan) == (state))

---

Enumeration Type Documentation

enum mwChannelState

channel status Enumeration values: mwChannel_NEW  channel is newly allocated, in the pool mwChannel_INIT  channel is being prepared, out of the pool mwChannel_WAIT  channel is waiting for accept mwChannel_OPEN  channel is accepted and open mwChannel_DESTROY  channel is being destroyed mwChannel_ERROR  channel is being destroyed due to error mwChannel_UNKNOWN  unknown state, or error determining state

enum mwChannelStatField

channel statistic fields. See also: mwChannel_getStatistic Enumeration values: mwChannelStat_MSG_SENT  total send-on-chan messages sent mwChannelStat_MSG_RECV  total send-on-chan messages received mwChannelStat_U_BYTES_SENT  total bytes sent, pre-encryption mwChannelStat_U_BYTES_RECV  total bytes received, post-decryption mwChannelStat_OPENED_AT  time when channel was opened mwChannelStat_CLOSED_AT  time when channel was closed

---

Function Documentation

int mwChannel_accept (  struct mwChannel *  chan  )

Formally accept an incoming channel. Instructs the session to send a channel accept message to the server, and to mark the channel as being OPEN.

void mwChannel_addSupportedCipherInstance (  struct mwChannel *  chan, struct mwCipherInstance *  ci )

add a cipher instance to a channel's list of supported ciphers. Channel must be NEW.

int mwChannel_create (  struct mwChannel *  chan  )

Formally open a channel. For outgoing channels: instruct the session to send a channel create message to the server, and to mark the channel (which must be in INIT status) as being in WAIT status. For incoming channels: configures the channel according to options in the channel create message. Marks the channel as being in WAIT status

int mwChannel_destroy (  struct mwChannel *  chan, guint32  reason, struct mwOpaque *  data )

Destroy a channel. Sends a channel-destroy message to the server, and perform cleanup to remove the channel. Parameters: chan  the channel to destroy reason  the reason code for closing the channel data  optional additional information

struct mwChannel* mwChannel_find (  struct mwChannelSet *  cs, guint32  chan )

Obtain a reference to a channel by its id. Returns: the channel matching chan, or NULL

struct mwOpaque* mwChannel_getAddtlAccept (  struct mwChannel *   )

direct reference to the accept addtl information for a channel

struct mwOpaque* mwChannel_getAddtlCreate (  struct mwChannel *   )

direct reference to the create addtl information for a channel

guint32 mwChannel_getId (  struct mwChannel *   )

get the ID for a channel. 0x00 indicates an error, as that is not a permissible value

guint32 mwChannel_getOptions (  struct mwChannel *  chan  )

guint32 mwChannel_getProtoType (  struct mwChannel *  chan  )

guint32 mwChannel_getProtoVer (  struct mwChannel *  chan  )

struct mwService* mwChannel_getService (  struct mwChannel *   )

get the service for a channel. This may be NULL for NEW channels

gpointer mwChannel_getServiceData (  struct mwChannel *  chan  )

get service-specific data. This is for use by service implementations to easily associate information with the channel

guint32 mwChannel_getServiceId (  struct mwChannel *   )

get the ID of the service for a channel. This may be 0x00 for NEW channels

struct mwSession* mwChannel_getSession (  struct mwChannel *   )

get the session for a channel.

enum mwChannelState mwChannel_getState (  struct mwChannel *   )

get the state of a channel

gpointer mwChannel_getStatistic (  struct mwChannel *  chan, enum mwChannelStatField  stat )

obtain the value for a statistic field as a gpointer

GList* mwChannel_getSupportedCipherInstances (  struct mwChannel *  chan  )

the list of supported ciphers for a channel. This list will be empty once a cipher has been selected for the channel

struct mwLoginInfo* mwChannel_getUser (  struct mwChannel *  chan  )

User at the other end of the channel. The target user for outgoing channels, the creator for incoming channels

struct mwChannel* mwChannel_newIncoming (  struct mwChannelSet *  , guint32  id )

Create an incoming channel with the given channel id. Channel's state will be set to WAIT. Primarily for use in mw_session

struct mwChannel* mwChannel_newOutgoing (  struct mwChannelSet *   )

Create an outgoing channel. Its channel ID will be generated by the owning channel set. Channel's state will be set to INIT

void mwChannel_populateSupportedCipherInstances (  struct mwChannel *  chan  )

automatically adds instances of all ciphers in the session to the list of supported ciphers for a channel

void mwChannel_recv (  struct mwChannel *  chan, struct mwMsgChannelSend *  msg )

Feed data into a channel.

void mwChannel_recvAccept (  struct mwChannel *  chan, struct mwMsgChannelAccept *  msg )

void mwChannel_recvCreate (  struct mwChannel *  chan, struct mwMsgChannelCreate *  msg )

void mwChannel_recvDestroy (  struct mwChannel *  chan, struct mwMsgChannelDestroy *  msg )

void mwChannel_removeServiceData (  struct mwChannel *  chan  )

void mwChannel_selectCipherInstance (  struct mwChannel *  chan, struct mwCipherInstance *  ci )

select a cipher instance for a channel. A NULL instance indicates that no encryption should be used.

int mwChannel_send (  struct mwChannel *  chan, guint32  msg_type, struct mwOpaque *  msg )

Compose a send-on-channel message, encrypt it as per the channel's specification, and send it.

int mwChannel_sendEncrypted (  struct mwChannel *  chan, guint32  msg_type, struct mwOpaque *  msg, gboolean  encrypt )

Compose a send-on-channel message, and if encrypt is TRUE, encrypt it as per the channel's specification, and send it.

void mwChannel_setOptions (  struct mwChannel *  chan, guint32  options )

void mwChannel_setProtoType (  struct mwChannel *  chan, guint32  proto_type )

void mwChannel_setProtoVer (  struct mwChannel *  chan, guint32  proto_ver )

void mwChannel_setService (  struct mwChannel *  chan, struct mwService *  srvc )

associate a channel with an owning service

void mwChannel_setServiceData (  struct mwChannel *  chan, gpointer  data, GDestroyNotify  clean )

set service-specific data. This is for use by service implementations to easily associate information with the channel

void mwChannelSet_free (  struct mwChannelSet *   )

Clear and deallocate a channel set. Closes, clears, and frees all contained channels.

struct mwChannelSet* mwChannelSet_new (  struct mwSession *   )

Allocate and initialize a channel set for a session.

---