Blame src/mw_channel.h

Packit 16808d
Packit 16808d
/*
Packit 16808d
  Meanwhile - Unofficial Lotus Sametime Community Client Library
Packit 16808d
  Copyright (C) 2004  Christopher (siege) O'Brien
Packit 16808d
  
Packit 16808d
  This library is free software; you can redistribute it and/or
Packit 16808d
  modify it under the terms of the GNU Library General Public
Packit 16808d
  License as published by the Free Software Foundation; either
Packit 16808d
  version 2 of the License, or (at your option) any later version.
Packit 16808d
  
Packit 16808d
  This library is distributed in the hope that it will be useful,
Packit 16808d
  but WITHOUT ANY WARRANTY; without even the implied warranty of
Packit 16808d
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Packit 16808d
  Library General Public License for more details.
Packit 16808d
  
Packit 16808d
  You should have received a copy of the GNU Library General Public
Packit 16808d
  License along with this library; if not, write to the Free
Packit 16808d
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
Packit 16808d
*/
Packit 16808d
Packit 16808d
#ifndef _MW_CHANNEL_H
Packit 16808d
#define _MW_CHANNEL_H
Packit 16808d
Packit 16808d
Packit 16808d
/** @file mw_channel.h
Packit 16808d
    
Packit 16808d
Life-cycle of an outgoing channel:
Packit 16808d
Packit 16808d
1: mwChannel_new is called. If there is a channel in the outgoing
Packit 16808d
collection in state NEW, then it is returned. Otherwise, a channel
Packit 16808d
is allocated, assigned a unique outgoing id, marked as NEW, and
Packit 16808d
returned.
Packit 16808d
Packit 16808d
2: channel is set to INIT status (effectively earmarking it as in-
Packit 16808d
use).  fields on the channel can then be set as necessary to
Packit 16808d
prepare it for creation.
Packit 16808d
Packit 16808d
3: mwChannel_create is called. The channel is marked to WAIT status
Packit 16808d
and a message is sent to the server. The channel is also marked as
Packit 16808d
inactive as of that moment.
Packit 16808d
Packit 16808d
4: the channel is accepted (step 5) or rejected (step 7)
Packit 16808d
Packit 16808d
5: an accept message is received from the server, and the channel
Packit 16808d
is marked as OPEN, and the inactive mark is removed. And messages
Packit 16808d
in the in or out queues for that channel are processed. The channel
Packit 16808d
is now ready to be used.
Packit 16808d
Packit 16808d
6: data is sent and received over the channel
Packit 16808d
Packit 16808d
7: the channel is closed either by receipt of a close message or by
Packit 16808d
local action. If by local action, then a close message is sent to
Packit 16808d
the server.  The channel is cleaned up, its queues dumped, and it
Packit 16808d
is set to NEW status to await re-use.
Packit 16808d
Packit 16808d
Life-cycle of an incoming channel:
Packit 16808d
Packit 16808d
1: a channel create message is received. A channel is allocated and
Packit 16808d
given an id matching the message. It is placed in status WAIT, and
Packit 16808d
marked as inactive as of that moment. The service matching that
Packit 16808d
channel is alerted of the incoming creation request.
Packit 16808d
Packit 16808d
2: the service can either accept (step 3) or reject (step 5) the
Packit 16808d
channel
Packit 16808d
Packit 16808d
3: mwChannel_accept is called. The channel is marked as OPEN, and
Packit 16808d
an accept message is sent to the server. And messages in the in or
Packit 16808d
out queues for that channel are processed. The channel is now ready
Packit 16808d
to be used.
Packit 16808d
Packit 16808d
4: data is sent and received over the channel
Packit 16808d
Packit 16808d
5: The channel is closed either by receipt of a close message or by
Packit 16808d
local action. If by local action, then a close message is sent to
Packit 16808d
the server.  The channel is cleaned up, its queues dumped, and it
Packit 16808d
is deallocated. */
Packit 16808d
Packit 16808d
Packit 16808d
#include <time.h>
Packit 16808d
#include "mw_common.h"
Packit 16808d
Packit 16808d
Packit 16808d
#ifdef __cplusplus
Packit 16808d
extern "C" {
Packit 16808d
#endif
Packit 16808d
Packit 16808d
Packit 16808d
/* place-holders */
Packit 16808d
struct mwCipherInstance;
Packit 16808d
struct mwMsgChannelAccept;
Packit 16808d
struct mwMsgChannelCreate;
Packit 16808d
struct mwMsgChannelDestroy;
Packit 16808d
struct mwMsgChannelSend;
Packit 16808d
struct mwService;
Packit 16808d
struct mwSession;
Packit 16808d
Packit 16808d
Packit 16808d
Packit 16808d
/** @struct mwChannel
Packit 16808d
    Represents a channel to a service */
Packit 16808d
struct mwChannel;
Packit 16808d
Packit 16808d
Packit 16808d
/** @struct mwChannelSet
Packit 16808d
    Collection of channels */
Packit 16808d
struct mwChannelSet;
Packit 16808d
Packit 16808d
Packit 16808d
/** special ID indicating the master channel */
Packit 16808d
#define MW_MASTER_CHANNEL_ID  0x00000000
Packit 16808d
Packit 16808d
Packit 16808d
/** non-zero if a channel id appears to be that of an outgoing channel */
Packit 16808d
#define mwChannel_idIsOutgoing(id) \
Packit 16808d
  (! (0x80000000 & (id)))
Packit 16808d
Packit 16808d
/** non-zero if a channel id appears to be that of an incoming channel */
Packit 16808d
#define mwChannel_idIsIncoming(id) \
Packit 16808d
  (! mwChannel_idIsOutgoing(id))
Packit 16808d
Packit 16808d
/** non-zero if a channel appears to be an outgoing channel */
Packit 16808d
#define mwChannel_isOutgoing(chan) \
Packit 16808d
  mwChannel_idIsOutgoing(mwChannel_getId(chan))
Packit 16808d
Packit 16808d
/** non-zero if a channel appears to be an incoming channel */
Packit 16808d
#define mwChannel_isIncoming(chan) \
Packit 16808d
  mwChannel_idIsIncoming(mwChannel_getId(chan))
Packit 16808d
Packit 16808d
Packit 16808d
/** channel status */
Packit 16808d
enum mwChannelState {
Packit 16808d
  mwChannel_NEW,      /**< channel is newly allocated, in the pool */
Packit 16808d
  mwChannel_INIT,     /**< channel is being prepared, out of the pool */
Packit 16808d
  mwChannel_WAIT,     /**< channel is waiting for accept */
Packit 16808d
  mwChannel_OPEN,     /**< channel is accepted and open */
Packit 16808d
  mwChannel_DESTROY,  /**< channel is being destroyed */
Packit 16808d
  mwChannel_ERROR,    /**< channel is being destroyed due to error */
Packit 16808d
  mwChannel_UNKNOWN,  /**< unknown state, or error determining state */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
#define mwChannel_isState(chan, state) \
Packit 16808d
  (mwChannel_getState(chan) == (state))
Packit 16808d
Packit 16808d
Packit 16808d
/** channel statistic fields.
Packit 16808d
    @see mwChannel_getStatistic */
Packit 16808d
enum mwChannelStatField {
Packit 16808d
  mwChannelStat_MSG_SENT,      /**< total send-on-chan messages sent */
Packit 16808d
  mwChannelStat_MSG_RECV,      /**< total send-on-chan messages received */
Packit 16808d
  mwChannelStat_U_BYTES_SENT,  /**< total bytes sent, pre-encryption */
Packit 16808d
  mwChannelStat_U_BYTES_RECV,  /**< total bytes received, post-decryption */
Packit 16808d
  mwChannelStat_OPENED_AT,     /**< time when channel was opened */
Packit 16808d
  mwChannelStat_CLOSED_AT,     /**< time when channel was closed */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/** @enum mwEncryptPolicy
Packit 16808d
Packit 16808d
    Policy for a channel, dictating what sort of encryption should be
Packit 16808d
    used, if any, and when.
Packit 16808d
*/
Packit 16808d
enum mwEncryptPolicy {
Packit 16808d
  mwEncrypt_NONE      = 0x0000, /**< encrypt none */
Packit 16808d
  mwEncrypt_WHATEVER  = 0x0001, /**< encrypt whatever you want */
Packit 16808d
  mwEncrypt_ALL       = 0x0002, /**< encrypt all, any cipher */
Packit 16808d
  mwEncrypt_RC2_40    = 0x1000, /**< encrypt all, RC2/40 cipher */
Packit 16808d
  mwEncrypt_RC2_128   = 0x2000, /**< encrypt all, RC2/128 cipher */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/** Allocate and initialize a channel set for a session */
Packit 16808d
struct mwChannelSet *mwChannelSet_new(struct mwSession *);
Packit 16808d
Packit 16808d
Packit 16808d
/** Clear and deallocate a channel set. Closes, clears, and frees all
Packit 16808d
    contained channels. */
Packit 16808d
void mwChannelSet_free(struct mwChannelSet *);
Packit 16808d
Packit 16808d
Packit 16808d
/** Create an incoming channel with the given channel id. Channel's state
Packit 16808d
    will be set to WAIT. Primarily for use in mw_session */
Packit 16808d
struct mwChannel *mwChannel_newIncoming(struct mwChannelSet *, guint32 id);
Packit 16808d
Packit 16808d
Packit 16808d
/** Create an outgoing channel. Its channel ID will be generated by
Packit 16808d
    the owning channel set. Channel's state will be set to INIT */
Packit 16808d
struct mwChannel *mwChannel_newOutgoing(struct mwChannelSet *);
Packit 16808d
Packit 16808d
Packit 16808d
/** Obtain a reference to a channel by its id.
Packit 16808d
    @returns the channel matching chan, or NULL */
Packit 16808d
struct mwChannel *mwChannel_find(struct mwChannelSet *cs, guint32 chan);
Packit 16808d
Packit 16808d
Packit 16808d
/** get the ID for a channel. 0x00 indicates an error, as that is not
Packit 16808d
    a permissible value */
Packit 16808d
guint32 mwChannel_getId(struct mwChannel *);
Packit 16808d
Packit 16808d
Packit 16808d
/** get the session for a channel. */
Packit 16808d
struct mwSession *mwChannel_getSession(struct mwChannel *);
Packit 16808d
Packit 16808d
Packit 16808d
/** get the ID of the service for a channel. This may be 0x00 for NEW
Packit 16808d
    channels */
Packit 16808d
guint32 mwChannel_getServiceId(struct mwChannel *);
Packit 16808d
Packit 16808d
Packit 16808d
/** get the service for a channel. This may be NULL for NEW
Packit 16808d
    channels */
Packit 16808d
struct mwService *mwChannel_getService(struct mwChannel *);
Packit 16808d
Packit 16808d
Packit 16808d
/** associate a channel with an owning service */
Packit 16808d
void mwChannel_setService(struct mwChannel *chan, struct mwService *srvc);
Packit 16808d
Packit 16808d
Packit 16808d
/** get service-specific data. This is for use by service
Packit 16808d
    implementations to easily associate information with the
Packit 16808d
    channel */
Packit 16808d
gpointer mwChannel_getServiceData(struct mwChannel *chan);
Packit 16808d
Packit 16808d
Packit 16808d
/** set service-specific data. This is for use by service
Packit 16808d
    implementations to easily associate information with the
Packit 16808d
    channel */
Packit 16808d
void mwChannel_setServiceData(struct mwChannel *chan,
Packit 16808d
			      gpointer data, GDestroyNotify clean);
Packit 16808d
Packit 16808d
Packit 16808d
void mwChannel_removeServiceData(struct mwChannel *chan);
Packit 16808d
Packit 16808d
Packit 16808d
guint32 mwChannel_getProtoType(struct mwChannel *chan);
Packit 16808d
Packit 16808d
Packit 16808d
void mwChannel_setProtoType(struct mwChannel *chan, guint32 proto_type);
Packit 16808d
Packit 16808d
Packit 16808d
guint32 mwChannel_getProtoVer(struct mwChannel *chan);
Packit 16808d
Packit 16808d
Packit 16808d
void mwChannel_setProtoVer(struct mwChannel *chan, guint32 proto_ver);
Packit 16808d
Packit 16808d
Packit 16808d
/** Channel encryption policy.
Packit 16808d
Packit 16808d
    Cannot currently be set, used internally to automatically
Packit 16808d
    negotiate ciphers. Future revisions may allow this to be specified
Packit 16808d
    in a new channel to dictate channel encryption.
Packit 16808d
Packit 16808d
    @see enum mwEncryptPolicy
Packit 16808d
*/
Packit 16808d
guint16 mwChannel_getEncryptPolicy(struct mwChannel *chan);
Packit 16808d
Packit 16808d
Packit 16808d
guint32 mwChannel_getOptions(struct mwChannel *chan);
Packit 16808d
Packit 16808d
Packit 16808d
void mwChannel_setOptions(struct mwChannel *chan, guint32 options);
Packit 16808d
Packit 16808d
Packit 16808d
/** User at the other end of the channel. The target user for outgoing
Packit 16808d
    channels, the creator for incoming channels */
Packit 16808d
struct mwLoginInfo *mwChannel_getUser(struct mwChannel *chan);
Packit 16808d
Packit 16808d
Packit 16808d
/** direct reference to the create addtl information for a channel */
Packit 16808d
struct mwOpaque *mwChannel_getAddtlCreate(struct mwChannel *);
Packit 16808d
Packit 16808d
Packit 16808d
/** direct reference to the accept addtl information for a channel */
Packit 16808d
struct mwOpaque *mwChannel_getAddtlAccept(struct mwChannel *);
Packit 16808d
Packit 16808d
Packit 16808d
/** automatically adds instances of all ciphers in the session to the
Packit 16808d
    list of supported ciphers for a channel */
Packit 16808d
void mwChannel_populateSupportedCipherInstances(struct mwChannel *chan);
Packit 16808d
Packit 16808d
Packit 16808d
/** add a cipher instance to a channel's list of supported
Packit 16808d
    ciphers. Channel must be NEW. */
Packit 16808d
void mwChannel_addSupportedCipherInstance(struct mwChannel *chan,
Packit 16808d
					  struct mwCipherInstance *ci);
Packit 16808d
Packit 16808d
Packit 16808d
/** the list of supported ciphers for a channel. This list will be
Packit 16808d
    empty once a cipher has been selected for the channel */
Packit 16808d
GList *mwChannel_getSupportedCipherInstances(struct mwChannel *chan);
Packit 16808d
Packit 16808d
Packit 16808d
/** select a cipher instance for a channel. A NULL instance indicates
Packit 16808d
    that no encryption should be used. */
Packit 16808d
void mwChannel_selectCipherInstance(struct mwChannel *chan,
Packit 16808d
				    struct mwCipherInstance *ci);
Packit 16808d
Packit 16808d
Packit 16808d
struct mwCipherInstance *
Packit 16808d
mwChannel_getCipherInstance(struct mwChannel *chan);
Packit 16808d
Packit 16808d
Packit 16808d
/** get the state of a channel  */
Packit 16808d
enum mwChannelState mwChannel_getState(struct mwChannel *);
Packit 16808d
Packit 16808d
Packit 16808d
/** obtain the value for a statistic field as a gpointer */
Packit 16808d
gpointer mwChannel_getStatistic(struct mwChannel *chan,
Packit 16808d
				enum mwChannelStatField stat);
Packit 16808d
Packit 16808d
Packit 16808d
/** Formally open a channel.
Packit 16808d
Packit 16808d
    For outgoing channels: instruct the session to send a channel
Packit 16808d
    create message to the server, and to mark the channel (which must
Packit 16808d
    be in INIT status) as being in WAIT status.
Packit 16808d
   
Packit 16808d
    For incoming channels: configures the channel according to options
Packit 16808d
    in the channel create message. Marks the channel as being in WAIT
Packit 16808d
    status
Packit 16808d
*/
Packit 16808d
int mwChannel_create(struct mwChannel *chan);
Packit 16808d
Packit 16808d
Packit 16808d
/** Formally accept an incoming channel. Instructs the session to send
Packit 16808d
    a channel accept message to the server, and to mark the channel as
Packit 16808d
    being OPEN. */
Packit 16808d
int mwChannel_accept(struct mwChannel *chan);
Packit 16808d
Packit 16808d
Packit 16808d
/** Destroy a channel. Sends a channel-destroy message to the server,
Packit 16808d
    and perform cleanup to remove the channel.
Packit 16808d
Packit 16808d
    @param chan    the channel to destroy
Packit 16808d
    @param reason  the reason code for closing the channel
Packit 16808d
    @param data    optional additional information 
Packit 16808d
*/
Packit 16808d
int mwChannel_destroy(struct mwChannel *chan, guint32 reason,
Packit 16808d
		      struct mwOpaque *data);
Packit 16808d
Packit 16808d
Packit 16808d
/** Compose a send-on-channel message, encrypt it as per the channel's
Packit 16808d
    specification, and send it */
Packit 16808d
int mwChannel_send(struct mwChannel *chan, guint32 msg_type,
Packit 16808d
		   struct mwOpaque *msg);
Packit 16808d
Packit 16808d
Packit 16808d
/** Compose a send-on-channel message, and if encrypt is TRUE, encrypt
Packit 16808d
    it as per the channel's specification, and send it */
Packit 16808d
int mwChannel_sendEncrypted(struct mwChannel *chan,
Packit 16808d
			    guint32 msg_type, struct mwOpaque *msg,
Packit 16808d
			    gboolean encrypt);
Packit 16808d
Packit 16808d
Packit 16808d
/** pass a create message to a channel for handling */
Packit 16808d
void mwChannel_recvCreate(struct mwChannel *chan,
Packit 16808d
			  struct mwMsgChannelCreate *msg);
Packit 16808d
Packit 16808d
Packit 16808d
/** pass an accept message to a channel for handling */
Packit 16808d
void mwChannel_recvAccept(struct mwChannel *chan,
Packit 16808d
			  struct mwMsgChannelAccept *msg);
Packit 16808d
Packit 16808d
Packit 16808d
/** pass a destroy message to a channel for handling */
Packit 16808d
void mwChannel_recvDestroy(struct mwChannel *chan,
Packit 16808d
			   struct mwMsgChannelDestroy *msg);
Packit 16808d
Packit 16808d
Packit 16808d
/** Feed data into a channel. */
Packit 16808d
void mwChannel_recv(struct mwChannel *chan, struct mwMsgChannelSend *msg);
Packit 16808d
Packit 16808d
Packit 16808d
#ifdef __cplusplus
Packit 16808d
}
Packit 16808d
#endif
Packit 16808d
Packit 16808d
Packit 16808d
#endif /* _MW_CHANNEL_H */
Packit 16808d