meanwhile  1.0.2
Macros | Enumerations | Functions
mw_channel.h File Reference

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

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

Go to the source code of this file.

Macros

#define MW_MASTER_CHANNEL_ID   0x00000000
 special ID indicating the master channel More...
 
#define mwChannel_idIsIncoming(id)   (! mwChannel_idIsOutgoing(id))
 non-zero if a channel id appears to be that of an incoming channel More...
 
#define mwChannel_idIsOutgoing(id)   (! (0x80000000 & (id)))
 non-zero if a channel id appears to be that of an outgoing channel More...
 
#define mwChannel_isIncoming(chan)   mwChannel_idIsIncoming(mwChannel_getId(chan))
 non-zero if a channel appears to be an incoming channel More...
 
#define mwChannel_isOutgoing(chan)   mwChannel_idIsOutgoing(mwChannel_getId(chan))
 non-zero if a channel appears to be an outgoing channel More...
 
#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...
 
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. More...
 
void mwChannel_addSupportedCipherInstance (struct mwChannel *chan, struct mwCipherInstance *ci)
 add a cipher instance to a channel's list of supported ciphers. More...
 
int mwChannel_create (struct mwChannel *chan)
 Formally open a channel. More...
 
int mwChannel_destroy (struct mwChannel *chan, guint32 reason, struct mwOpaque *data)
 Destroy a channel. More...
 
struct mwChannelmwChannel_find (struct mwChannelSet *cs, guint32 chan)
 Obtain a reference to a channel by its id. More...
 
struct mwOpaquemwChannel_getAddtlAccept (struct mwChannel *)
 direct reference to the accept addtl information for a channel More...
 
struct mwOpaquemwChannel_getAddtlCreate (struct mwChannel *)
 direct reference to the create addtl information for a channel More...
 
struct mwCipherInstancemwChannel_getCipherInstance (struct mwChannel *chan)
 
guint16 mwChannel_getEncryptPolicy (struct mwChannel *chan)
 Channel encryption policy. More...
 
guint32 mwChannel_getId (struct mwChannel *)
 get the ID for a channel. More...
 
guint32 mwChannel_getOptions (struct mwChannel *chan)
 
guint32 mwChannel_getProtoType (struct mwChannel *chan)
 
guint32 mwChannel_getProtoVer (struct mwChannel *chan)
 
struct mwServicemwChannel_getService (struct mwChannel *)
 get the service for a channel. More...
 
gpointer mwChannel_getServiceData (struct mwChannel *chan)
 get service-specific data. More...
 
guint32 mwChannel_getServiceId (struct mwChannel *)
 get the ID of the service for a channel. More...
 
struct mwSessionmwChannel_getSession (struct mwChannel *)
 get the session for a channel. More...
 
enum mwChannelState mwChannel_getState (struct mwChannel *)
 get the state of a channel More...
 
gpointer mwChannel_getStatistic (struct mwChannel *chan, enum mwChannelStatField stat)
 obtain the value for a statistic field as a gpointer More...
 
GList * mwChannel_getSupportedCipherInstances (struct mwChannel *chan)
 the list of supported ciphers for a channel. More...
 
struct mwLoginInfomwChannel_getUser (struct mwChannel *chan)
 User at the other end of the channel. More...
 
struct mwChannelmwChannel_newIncoming (struct mwChannelSet *, guint32 id)
 Create an incoming channel with the given channel id. More...
 
struct mwChannelmwChannel_newOutgoing (struct mwChannelSet *)
 Create an outgoing channel. More...
 
void mwChannel_populateSupportedCipherInstances (struct mwChannel *chan)
 automatically adds instances of all ciphers in the session to the list of supported ciphers for a channel More...
 
void mwChannel_recv (struct mwChannel *chan, struct mwMsgChannelSend *msg)
 Feed data into a channel. More...
 
void mwChannel_recvAccept (struct mwChannel *chan, struct mwMsgChannelAccept *msg)
 pass an accept message to a channel for handling More...
 
void mwChannel_recvCreate (struct mwChannel *chan, struct mwMsgChannelCreate *msg)
 pass a create message to a channel for handling More...
 
void mwChannel_recvDestroy (struct mwChannel *chan, struct mwMsgChannelDestroy *msg)
 pass a destroy message to a channel for handling More...
 
void mwChannel_removeServiceData (struct mwChannel *chan)
 
void mwChannel_selectCipherInstance (struct mwChannel *chan, struct mwCipherInstance *ci)
 select a cipher instance for a channel. More...
 
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. More...
 
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. More...
 
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 More...
 
void mwChannel_setServiceData (struct mwChannel *chan, gpointer data, GDestroyNotify clean)
 set service-specific data. More...
 
void mwChannelSet_free (struct mwChannelSet *)
 Clear and deallocate a channel set. More...
 
struct mwChannelSetmwChannelSet_new (struct mwSession *)
 Allocate and initialize a channel set for a session. More...
 

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)    (! mwChannel_idIsOutgoing(id))

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

◆ mwChannel_idIsOutgoing

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

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

◆ mwChannel_isIncoming

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

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

◆ mwChannel_isOutgoing

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

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

◆ mwChannel_isState

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

Enumeration Type Documentation

◆ 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

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

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.

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

◆ 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

◆ 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
chanthe channel to destroy
reasonthe reason code for closing the channel
dataoptional additional information

◆ 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

◆ mwChannel_getAddtlAccept()

struct mwOpaque* mwChannel_getAddtlAccept ( struct mwChannel )

direct reference to the accept addtl information for a channel

◆ mwChannel_getAddtlCreate()

struct mwOpaque* mwChannel_getAddtlCreate ( struct mwChannel )

direct reference to the create addtl information for a channel

◆ mwChannel_getCipherInstance()

struct mwCipherInstance* mwChannel_getCipherInstance ( struct mwChannel chan)

◆ 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

◆ mwChannel_getId()

guint32 mwChannel_getId ( struct mwChannel )

get the ID for a channel.

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

◆ mwChannel_getOptions()

guint32 mwChannel_getOptions ( struct mwChannel chan)

◆ mwChannel_getProtoType()

guint32 mwChannel_getProtoType ( struct mwChannel chan)

◆ mwChannel_getProtoVer()

guint32 mwChannel_getProtoVer ( struct mwChannel chan)

◆ mwChannel_getService()

struct mwService* mwChannel_getService ( struct mwChannel )

get the service for a channel.

This may be NULL for NEW channels

◆ 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

◆ mwChannel_getServiceId()

guint32 mwChannel_getServiceId ( struct mwChannel )

get the ID of the service for a channel.

This may be 0x00 for NEW channels

◆ mwChannel_getSession()

struct mwSession* mwChannel_getSession ( struct mwChannel )

get the session for a channel.

◆ mwChannel_getState()

enum mwChannelState mwChannel_getState ( struct mwChannel )

get the state of a channel

◆ mwChannel_getStatistic()

gpointer mwChannel_getStatistic ( struct mwChannel chan,
enum mwChannelStatField  stat 
)

obtain the value for a statistic field as a gpointer

◆ 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

◆ 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

◆ 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

◆ 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

◆ 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

◆ mwChannel_recv()

void mwChannel_recv ( struct mwChannel chan,
struct mwMsgChannelSend msg 
)

Feed data into a channel.

◆ mwChannel_recvAccept()

void mwChannel_recvAccept ( struct mwChannel chan,
struct mwMsgChannelAccept msg 
)

pass an accept message to a channel for handling

◆ mwChannel_recvCreate()

void mwChannel_recvCreate ( struct mwChannel chan,
struct mwMsgChannelCreate msg 
)

pass a create message to a channel for handling

◆ mwChannel_recvDestroy()

void mwChannel_recvDestroy ( struct mwChannel chan,
struct mwMsgChannelDestroy msg 
)

pass a destroy message to a channel for handling

◆ mwChannel_removeServiceData()

void mwChannel_removeServiceData ( struct mwChannel chan)

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

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

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

◆ mwChannel_setOptions()

void mwChannel_setOptions ( struct mwChannel chan,
guint32  options 
)

◆ mwChannel_setProtoType()

void mwChannel_setProtoType ( struct mwChannel chan,
guint32  proto_type 
)

◆ mwChannel_setProtoVer()

void mwChannel_setProtoVer ( struct mwChannel chan,
guint32  proto_ver 
)

◆ mwChannel_setService()

void mwChannel_setService ( struct mwChannel chan,
struct mwService srvc 
)

associate a channel with an owning service

◆ 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

◆ mwChannelSet_free()

void mwChannelSet_free ( struct mwChannelSet )

Clear and deallocate a channel set.

Closes, clears, and frees all contained channels.

◆ mwChannelSet_new()

struct mwChannelSet* mwChannelSet_new ( struct mwSession )

Allocate and initialize a channel set for a session.