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