Life-cycle of an outgoing channel: More...

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

Macros
#define	MW_MASTER_CHANNEL_ID 0x00000000
	special ID indicating the master channel
#define	mwChannel_idIsIncoming(id)
	non-zero if a channel id appears to be that of an incoming channel
#define	mwChannel_idIsOutgoing(id)
	non-zero if a channel id appears to be that of an outgoing channel
#define	mwChannel_isIncoming(chan)
	non-zero if a channel appears to be an incoming channel
#define	mwChannel_isOutgoing(chan)
	non-zero if a channel appears to be an outgoing channel
#define	mwChannel_isState(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...
enum	mwEncryptPolicy { mwEncrypt_NONE = 0x0000 , mwEncrypt_WHATEVER = 0x0001 , mwEncrypt_ALL = 0x0002 , mwEncrypt_RC2_40 = 0x1000 , mwEncrypt_RC2_128 = 0x2000 }
	Policy for a channel, dictating what sort of encryption should be used, if any, and when. 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.
struct mwChannel *	mwChannel_find (struct mwChannelSet *cs, guint32 chan)
	Obtain a reference to a channel by its id.
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
struct mwCipherInstance *	mwChannel_getCipherInstance (struct mwChannel *chan)
guint16	mwChannel_getEncryptPolicy (struct mwChannel *chan)
	Channel encryption policy.
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)
struct 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.
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.
struct mwLoginInfo *	mwChannel_getUser (struct mwChannel *chan)
	User at the other end of the channel.
struct mwChannel *	mwChannel_newIncoming (struct mwChannelSet *, guint32 id)
	Create an incoming channel with the given channel id.
struct 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)
	pass an accept message to a channel for handling
void	mwChannel_recvCreate (struct mwChannel chan, struct mwMsgChannelCreate msg)
	pass a create message to a channel for handling
void	mwChannel_recvDestroy (struct mwChannel chan, struct mwMsgChannelDestroy msg)
	pass a destroy message to a channel for handling
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.
struct mwChannelSet *	mwChannelSet_new (struct mwSession *)
	Allocate and initialize a channel set for a session.

Detailed Description

Life-cycle of an outgoing channel:

1: mwChannel_new is called. If there is a channel in the outgoing collection in state NEW, then it is returned. Otherwise, a channel is allocated, assigned a unique outgoing id, marked as NEW, and returned.

2: channel is set to INIT status (effectively earmarking it as in- use). fields on the channel can then be set as necessary to prepare it for creation.

3: mwChannel_create is called. The channel is marked to WAIT status and a message is sent to the server. The channel is also marked as inactive as of that moment.

4: the channel is accepted (step 5) or rejected (step 7)

5: an accept message is received from the server, and the channel is marked as OPEN, and the inactive mark is removed. And messages in the in or out queues for that channel are processed. The channel is now ready to be used.

6: data is sent and received over the channel

7: the channel is closed either by receipt of a close message or by local action. If by local action, then a close message is sent to the server. The channel is cleaned up, its queues dumped, and it is set to NEW status to await re-use.

Life-cycle of an incoming channel:

1: a channel create message is received. A channel is allocated and given an id matching the message. It is placed in status WAIT, and marked as inactive as of that moment. The service matching that channel is alerted of the incoming creation request.

2: the service can either accept (step 3) or reject (step 5) the channel

3: mwChannel_accept is called. The channel is marked as OPEN, and an accept message is sent to the server. And messages in the in or out queues for that channel are processed. The channel is now ready to be used.

4: data is sent and received over the channel

5: The channel is closed either by receipt of a close message or by local action. If by local action, then a close message is sent to the server. The channel is cleaned up, its queues dumped, and it is deallocated.

Macro Definition Documentation

◆ MW_MASTER_CHANNEL_ID

#define MW_MASTER_CHANNEL_ID 0x00000000

special ID indicating the master channel

◆ mwChannel_idIsIncoming

#define mwChannel_idIsIncoming ( id )

Value:

(! mwChannel_idIsOutgoing(id))

mwChannel_idIsOutgoing

#define mwChannel_idIsOutgoing(id)

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

Definition mw_channel.h:114

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

◆ mwChannel_idIsOutgoing

#define mwChannel_idIsOutgoing ( id )

Value:

(! (0x80000000 & (id)))

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

◆ mwChannel_isIncoming

#define mwChannel_isIncoming ( chan )

Value:

mwChannel_idIsIncoming(mwChannel_getId(chan))

mwChannel_getId

guint32 mwChannel_getId(struct mwChannel *)

get the ID for a channel.

mwChannel_idIsIncoming

#define mwChannel_idIsIncoming(id)

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

Definition mw_channel.h:118

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

◆ mwChannel_isOutgoing

#define mwChannel_isOutgoing ( chan )

Value:

mwChannel_idIsOutgoing(mwChannel_getId(chan))

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

◆ mwChannel_isState

#define mwChannel_isState	(		chan,
			state )

Value:

(mwChannel_getState(chan) == (state))

mwChannel_getState

enum mwChannelState mwChannel_getState(struct mwChannel *)

get the state of a channel

Enumeration Type Documentation

◆ mwChannelState

enum mwChannelState

channel status

Enumerator
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

◆ mwChannelStatField

enum mwChannelStatField

channel statistic fields.

See also: mwChannel_getStatistic

Enumerator
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

◆ mwEncryptPolicy

enum mwEncryptPolicy

Policy for a channel, dictating what sort of encryption should be used, if any, and when.

Enumerator
mwEncrypt_NONE	encrypt none
mwEncrypt_WHATEVER	encrypt whatever you want
mwEncrypt_ALL	encrypt all, any cipher
mwEncrypt_RC2_40	encrypt all, RC2/40 cipher
mwEncrypt_RC2_128	encrypt all, RC2/128 cipher

Function Documentation

◆ mwChannel_accept()

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.

References mwChannel_accept().

Referenced by mwChannel_accept().

◆ mwChannel_addSupportedCipherInstance()

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.

References mwChannel_addSupportedCipherInstance().

Referenced by mwChannel_addSupportedCipherInstance().

◆ mwChannel_create()

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

References mwChannel_create().

Referenced by mwChannel_create().

◆ mwChannel_destroy()

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

References mwChannel_destroy().

Referenced by mwChannel_destroy().

◆ mwChannel_find()

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

References mwChannel_find().

Referenced by mwChannel_find().

◆ mwChannel_getAddtlAccept()

struct mwOpaque * mwChannel_getAddtlAccept ( struct mwChannel * )

direct reference to the accept addtl information for a channel

References mwChannel_getAddtlAccept().

Referenced by mwChannel_getAddtlAccept().

◆ mwChannel_getAddtlCreate()

struct mwOpaque * mwChannel_getAddtlCreate ( struct mwChannel * )

direct reference to the create addtl information for a channel

References mwChannel_getAddtlCreate().

Referenced by mwChannel_getAddtlCreate().

◆ mwChannel_getCipherInstance()

struct mwCipherInstance * mwChannel_getCipherInstance ( struct mwChannel * chan )

References mwChannel_getCipherInstance().

Referenced by mwChannel_getCipherInstance().

◆ mwChannel_getEncryptPolicy()

guint16 mwChannel_getEncryptPolicy ( struct mwChannel * chan )

Channel encryption policy.

Cannot currently be set, used internally to automatically negotiate ciphers. Future revisions may allow this to be specified in a new channel to dictate channel encryption.

See also: enum mwEncryptPolicy

References mwChannel_getEncryptPolicy().

Referenced by mwChannel_getEncryptPolicy().

◆ mwChannel_getId()

guint32 mwChannel_getId ( struct mwChannel * )

get the ID for a channel.

0x00 indicates an error, as that is not a permissible value

References mwChannel_getId().

Referenced by mwChannel_getId().

◆ mwChannel_getOptions()

guint32 mwChannel_getOptions ( struct mwChannel * chan )

References mwChannel_getOptions().

Referenced by mwChannel_getOptions().

◆ mwChannel_getProtoType()

guint32 mwChannel_getProtoType ( struct mwChannel * chan )

References mwChannel_getProtoType().

Referenced by mwChannel_getProtoType().

◆ mwChannel_getProtoVer()

guint32 mwChannel_getProtoVer ( struct mwChannel * chan )

References mwChannel_getProtoVer().

Referenced by mwChannel_getProtoVer().

◆ mwChannel_getService()

struct mwService * mwChannel_getService ( struct mwChannel * )

get the service for a channel.

This may be NULL for NEW channels

References mwChannel_getService().

Referenced by mwChannel_getService().

◆ mwChannel_getServiceData()

gpointer mwChannel_getServiceData ( struct mwChannel * chan )

get service-specific data.

This is for use by service implementations to easily associate information with the channel

References mwChannel_getServiceData().

Referenced by mwChannel_getServiceData().

◆ mwChannel_getServiceId()

guint32 mwChannel_getServiceId ( struct mwChannel * )

get the ID of the service for a channel.

This may be 0x00 for NEW channels

References mwChannel_getServiceId().

Referenced by mwChannel_getServiceId().

◆ mwChannel_getSession()

struct mwSession * mwChannel_getSession ( struct mwChannel * )

get the session for a channel.

References mwChannel_getSession().

Referenced by mwChannel_getSession().

◆ mwChannel_getState()

enum mwChannelState mwChannel_getState ( struct mwChannel * )

get the state of a channel

References mwChannel_getState().

Referenced by mwChannel_getState().

◆ mwChannel_getStatistic()

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

obtain the value for a statistic field as a gpointer

References mwChannel_getStatistic().

Referenced by mwChannel_getStatistic().

◆ mwChannel_getSupportedCipherInstances()

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

References mwChannel_getSupportedCipherInstances().

Referenced by mwChannel_getSupportedCipherInstances().

◆ mwChannel_getUser()

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

References mwChannel_getUser().

Referenced by mwChannel_getUser().

◆ mwChannel_newIncoming()

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

References mwChannel_newIncoming().

Referenced by mwChannel_newIncoming().

◆ mwChannel_newOutgoing()

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

References mwChannel_newOutgoing().

Referenced by mwChannel_newOutgoing().

◆ mwChannel_populateSupportedCipherInstances()

void mwChannel_populateSupportedCipherInstances ( struct mwChannel * chan )

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

References mwChannel_populateSupportedCipherInstances().

Referenced by mwChannel_populateSupportedCipherInstances().

◆ mwChannel_recv()

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

Feed data into a channel.

References mwChannel_recv().

Referenced by mwChannel_recv().

◆ mwChannel_recvAccept()

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

pass an accept message to a channel for handling

References mwChannel_recvAccept().

Referenced by mwChannel_recvAccept().

◆ mwChannel_recvCreate()

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

pass a create message to a channel for handling

References mwChannel_recvCreate().

Referenced by mwChannel_recvCreate().

◆ mwChannel_recvDestroy()

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

pass a destroy message to a channel for handling

References mwChannel_recvDestroy().

Referenced by mwChannel_recvDestroy().

◆ mwChannel_removeServiceData()

void mwChannel_removeServiceData ( struct mwChannel * chan )

References mwChannel_removeServiceData().

Referenced by mwChannel_removeServiceData().

◆ mwChannel_selectCipherInstance()

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.

References mwChannel_selectCipherInstance().

Referenced by mwChannel_selectCipherInstance().

◆ mwChannel_send()

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.

References mwChannel_send().

Referenced by mwChannel_send().

◆ mwChannel_sendEncrypted()

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.

References mwChannel_sendEncrypted().

Referenced by mwChannel_sendEncrypted().

◆ mwChannel_setOptions()

void mwChannel_setOptions	(	struct mwChannel *	chan,
		guint32	options )

References mwChannel_setOptions().

Referenced by mwChannel_setOptions().

◆ mwChannel_setProtoType()

void mwChannel_setProtoType	(	struct mwChannel *	chan,
		guint32	proto_type )

References mwChannel_setProtoType().

Referenced by mwChannel_setProtoType().

◆ mwChannel_setProtoVer()

void mwChannel_setProtoVer	(	struct mwChannel *	chan,
		guint32	proto_ver )

References mwChannel_setProtoVer().

Referenced by mwChannel_setProtoVer().

◆ mwChannel_setService()

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

associate a channel with an owning service

References mwChannel_setService().

Referenced by mwChannel_setService().

◆ mwChannel_setServiceData()

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

References mwChannel_setServiceData().

Referenced by mwChannel_setServiceData().

◆ mwChannelSet_free()

void mwChannelSet_free ( struct mwChannelSet * )

Clear and deallocate a channel set.

Closes, clears, and frees all contained channels.

References mwChannelSet_free().

Referenced by mwChannelSet_free().

◆ mwChannelSet_new()

struct mwChannelSet * mwChannelSet_new ( struct mwSession * )

Allocate and initialize a channel set for a session.

References mwChannelSet_new().

Referenced by mwChannelSet_new().

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MW_MASTER_CHANNEL_ID

◆ mwChannel_idIsIncoming

◆ mwChannel_idIsOutgoing

◆ mwChannel_isIncoming

◆ mwChannel_isOutgoing

◆ mwChannel_isState

Enumeration Type Documentation

◆ mwChannelState

◆ mwChannelStatField

◆ mwEncryptPolicy

Function Documentation

◆ mwChannel_accept()

◆ mwChannel_addSupportedCipherInstance()

◆ mwChannel_create()

◆ mwChannel_destroy()

◆ mwChannel_find()

◆ mwChannel_getAddtlAccept()

◆ mwChannel_getAddtlCreate()

◆ mwChannel_getCipherInstance()

◆ mwChannel_getEncryptPolicy()

◆ mwChannel_getId()

◆ mwChannel_getOptions()

◆ mwChannel_getProtoType()

◆ mwChannel_getProtoVer()

◆ mwChannel_getService()

◆ mwChannel_getServiceData()

◆ mwChannel_getServiceId()

◆ mwChannel_getSession()

◆ mwChannel_getState()

◆ mwChannel_getStatistic()

◆ mwChannel_getSupportedCipherInstances()

◆ mwChannel_getUser()

◆ mwChannel_newIncoming()

◆ mwChannel_newOutgoing()

◆ mwChannel_populateSupportedCipherInstances()

◆ mwChannel_recv()

◆ mwChannel_recvAccept()

◆ mwChannel_recvCreate()

◆ mwChannel_recvDestroy()

◆ mwChannel_removeServiceData()

◆ mwChannel_selectCipherInstance()

◆ mwChannel_send()

◆ mwChannel_sendEncrypted()

◆ mwChannel_setOptions()

◆ mwChannel_setProtoType()

◆ mwChannel_setProtoVer()

◆ mwChannel_setService()

◆ mwChannel_setServiceData()

◆ mwChannelSet_free()

◆ mwChannelSet_new()