|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/*
|
|
Packit Service |
37472d |
Meanwhile - Unofficial Lotus Sametime Community Client Library
|
|
Packit Service |
37472d |
Copyright (C) 2004 Christopher (siege) O'Brien
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
This library is free software; you can redistribute it and/or
|
|
Packit Service |
37472d |
modify it under the terms of the GNU Library General Public
|
|
Packit Service |
37472d |
License as published by the Free Software Foundation; either
|
|
Packit Service |
37472d |
version 2 of the License, or (at your option) any later version.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
This library is distributed in the hope that it will be useful,
|
|
Packit Service |
37472d |
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
Packit Service |
37472d |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Packit Service |
37472d |
Library General Public License for more details.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
You should have received a copy of the GNU Library General Public
|
|
Packit Service |
37472d |
License along with this library; if not, write to the Free
|
|
Packit Service |
37472d |
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
Packit Service |
37472d |
*/
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#ifndef _MW_SRVC_IM_H
|
|
Packit Service |
37472d |
#define _MW_SRVC_IM_H
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @file mw_srvc_im.h
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
The IM service provides one-on-one communication between
|
|
Packit Service |
37472d |
users. Messages sent over conversations may relay different types
|
|
Packit Service |
37472d |
of information, in a variety of formats. The basic feature-set
|
|
Packit Service |
37472d |
provides plain-text chat with typing notification. More complex
|
|
Packit Service |
37472d |
features may be negotiated transparently by setting the IM Client
|
|
Packit Service |
37472d |
Type for a conversation, or for the service as a whole.
|
|
Packit Service |
37472d |
*/
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#include <glib.h>
|
|
Packit Service |
37472d |
#include "mw_common.h"
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#ifdef __cplusplus
|
|
Packit Service |
37472d |
extern "C" {
|
|
Packit Service |
37472d |
#endif
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/* identifier for the IM service */
|
|
Packit Service |
37472d |
#define mwService_IM 0x00001000
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @struct mwServiceIm
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
An instance of the IM service. This service provides simple
|
|
Packit Service |
37472d |
instant messaging functionality */
|
|
Packit Service |
37472d |
struct mwServiceIm;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @struct mwConversation
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
A conversation between the local service and a single other user */
|
|
Packit Service |
37472d |
struct mwConversation;
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
enum mwImClientType {
|
|
Packit Service |
37472d |
mwImClient_PLAIN = 0x00000001, /**< text, typing */
|
|
Packit Service |
37472d |
mwImClient_NOTESBUDDY = 0x00033453, /**< adds html, subject, mime */
|
|
Packit Service |
37472d |
mwImClient_PRECONF = 0x00000019, /**< pre-conference, legacy */
|
|
Packit Service |
37472d |
mwImClient_UNKNOWN = 0xffffffff, /**< trouble determining type */
|
|
Packit Service |
37472d |
};
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/**
|
|
Packit Service |
37472d |
Types of supported messages. When a conversation is created, the
|
|
Packit Service |
37472d |
least common denominator of features between either side of the
|
|
Packit Service |
37472d |
conversation (based on what features are available in the IM
|
|
Packit Service |
37472d |
service itself) becomes the set of supported features for that
|
|
Packit Service |
37472d |
conversation. At any point, the feature set for the service may
|
|
Packit Service |
37472d |
change, without affecting any existing conversations.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@see mwServiceIm_supports
|
|
Packit Service |
37472d |
@see mwServiceIm_setSupported
|
|
Packit Service |
37472d |
@see mwConversation_supports
|
|
Packit Service |
37472d |
@see mwConversation_send
|
|
Packit Service |
37472d |
@see mwServiceImHandler::conversation_recv
|
|
Packit Service |
37472d |
*/
|
|
Packit Service |
37472d |
enum mwImSendType {
|
|
Packit Service |
37472d |
mwImSend_PLAIN, /**< char *, plain-text message */
|
|
Packit Service |
37472d |
mwImSend_TYPING, /**< gboolean, typing status */
|
|
Packit Service |
37472d |
mwImSend_HTML, /**< char *, HTML formatted message (NOTESBUDDY) */
|
|
Packit Service |
37472d |
mwImSend_SUBJECT, /**< char *, conversation subject (NOTESBUDDY) */
|
|
Packit Service |
37472d |
mwImSend_MIME, /**< char *, MIME-encoded message (NOTESBUDDY) */
|
|
Packit Service |
37472d |
mwImSend_TIMESTAMP, /**< char *, YYYY:MM:DD:HH:mm:SS format (NOTESBUDDY) */
|
|
Packit Service |
37472d |
};
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @see mwConversation_getState */
|
|
Packit Service |
37472d |
enum mwConversationState {
|
|
Packit Service |
37472d |
mwConversation_CLOSED, /**< conversation is not open */
|
|
Packit Service |
37472d |
mwConversation_PENDING, /**< conversation is opening */
|
|
Packit Service |
37472d |
mwConversation_OPEN, /**< conversation is open */
|
|
Packit Service |
37472d |
mwConversation_UNKNOWN, /**< unknown state */
|
|
Packit Service |
37472d |
};
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#define mwConversation_isState(conv, state) \
|
|
Packit Service |
37472d |
(mwConversation_getState(conv) == (state))
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#define mwConversation_isClosed(conv) \
|
|
Packit Service |
37472d |
mwConversation_isState((conv), mwConversation_CLOSED)
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#define mwConversation_isPending(conv) \
|
|
Packit Service |
37472d |
mwConversation_isState((conv), mwConversation_PENDING)
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#define mwConversation_isOpen(conv) \
|
|
Packit Service |
37472d |
mwConversation_isState((conv), mwConversation_OPEN)
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** IM Service Handler. Provides functions for events triggered from an
|
|
Packit Service |
37472d |
IM service instance. */
|
|
Packit Service |
37472d |
struct mwImHandler {
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** A conversation has been successfully opened */
|
|
Packit Service |
37472d |
void (*conversation_opened)(struct mwConversation *conv);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** A conversation has been closed */
|
|
Packit Service |
37472d |
void (*conversation_closed)(struct mwConversation *conv, guint32 err);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** A message has been received on a conversation */
|
|
Packit Service |
37472d |
void (*conversation_recv)(struct mwConversation *conv,
|
|
Packit Service |
37472d |
enum mwImSendType type, gconstpointer msg);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Handle a Place invitation. Set this to NULL and we should end up
|
|
Packit Service |
37472d |
receiving a conference invitation instead. */
|
|
Packit Service |
37472d |
void (*place_invite)(struct mwConversation *conv,
|
|
Packit Service |
37472d |
const char *message,
|
|
Packit Service |
37472d |
const char *title, const char *name);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** optional. called from mwService_free */
|
|
Packit Service |
37472d |
void (*clear)(struct mwServiceIm *srvc);
|
|
Packit Service |
37472d |
};
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
struct mwServiceIm *mwServiceIm_new(struct mwSession *session,
|
|
Packit Service |
37472d |
struct mwImHandler *handler);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
struct mwImHandler *mwServiceIm_getHandler(struct mwServiceIm *srvc);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** reference an existing conversation to target, or create a new
|
|
Packit Service |
37472d |
conversation to target if one does not already exist */
|
|
Packit Service |
37472d |
struct mwConversation *mwServiceIm_getConversation(struct mwServiceIm *srvc,
|
|
Packit Service |
37472d |
struct mwIdBlock *target);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** reference an existing conversation to target */
|
|
Packit Service |
37472d |
struct mwConversation *mwServiceIm_findConversation(struct mwServiceIm *srvc,
|
|
Packit Service |
37472d |
struct mwIdBlock *target);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** determine if the conversations created from this service will
|
|
Packit Service |
37472d |
support a given send type */
|
|
Packit Service |
37472d |
gboolean mwServiceIm_supports(struct mwServiceIm *srvc,
|
|
Packit Service |
37472d |
enum mwImSendType type);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Set the default client type for the service. Newly created
|
|
Packit Service |
37472d |
conversations will attempt to meet this level of functionality
|
|
Packit Service |
37472d |
first.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@param srvc the IM service
|
|
Packit Service |
37472d |
@param type the send type to enable/disable
|
|
Packit Service |
37472d |
*/
|
|
Packit Service |
37472d |
void mwServiceIm_setClientType(struct mwServiceIm *srvc,
|
|
Packit Service |
37472d |
enum mwImClientType type);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
enum mwImClientType mwServiceIm_getClientType(struct mwServiceIm *srvc);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** attempt to open a conversation. If the conversation was not
|
|
Packit Service |
37472d |
already open and it is accepted,
|
|
Packit Service |
37472d |
mwServiceImHandler::conversation_opened will be triggered. Upon
|
|
Packit Service |
37472d |
failure, mwServiceImHandler::conversation_closed will be
|
|
Packit Service |
37472d |
triggered */
|
|
Packit Service |
37472d |
void mwConversation_open(struct mwConversation *conv);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** close a conversation. If the conversation was not already closed,
|
|
Packit Service |
37472d |
mwServiceImHandler::conversation_closed will be triggered */
|
|
Packit Service |
37472d |
void mwConversation_close(struct mwConversation *conv, guint32 err);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** determine whether a conversation supports the given message type */
|
|
Packit Service |
37472d |
gboolean mwConversation_supports(struct mwConversation *conv,
|
|
Packit Service |
37472d |
enum mwImSendType type);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
enum mwImClientType mwConversation_getClientType(struct mwConversation *conv);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** get the state of a conversation
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@see mwConversation_isOpen
|
|
Packit Service |
37472d |
@see mwConversation_isClosed
|
|
Packit Service |
37472d |
@see mwConversation_isPending
|
|
Packit Service |
37472d |
*/
|
|
Packit Service |
37472d |
enum mwConversationState mwConversation_getState(struct mwConversation *conv);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** send a message over an open conversation */
|
|
Packit Service |
37472d |
int mwConversation_send(struct mwConversation *conv,
|
|
Packit Service |
37472d |
enum mwImSendType type, gconstpointer send);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** @returns owning service for a conversation */
|
|
Packit Service |
37472d |
struct mwServiceIm *mwConversation_getService(struct mwConversation *conv);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** login information for conversation partner. returns NULL if conversation
|
|
Packit Service |
37472d |
is not OPEN */
|
|
Packit Service |
37472d |
struct mwLoginInfo *mwConversation_getTargetInfo(struct mwConversation *conv);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** ID for conversation partner */
|
|
Packit Service |
37472d |
struct mwIdBlock *mwConversation_getTarget(struct mwConversation *conv);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** set whether outgoing messages should be encrypted using the
|
|
Packit Service |
37472d |
negotiated cipher, if any */
|
|
Packit Service |
37472d |
void mwConversation_setEncrypted(struct mwConversation *conv,
|
|
Packit Service |
37472d |
gboolean useCipher);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** determine whether outgoing messages are being encrypted */
|
|
Packit Service |
37472d |
gboolean mwConversation_isEncrypted(struct mwConversation *conv);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Associates client data with a conversation. If there is existing data,
|
|
Packit Service |
37472d |
it will not have its cleanup function called.
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@see mwConversation_getClientData
|
|
Packit Service |
37472d |
@see mwConversation_removeClientData
|
|
Packit Service |
37472d |
*/
|
|
Packit Service |
37472d |
void mwConversation_setClientData(struct mwConversation *conv,
|
|
Packit Service |
37472d |
gpointer data, GDestroyNotify clean);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Reference associated client data
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@see mwConversation_setClientData
|
|
Packit Service |
37472d |
@see mwConversation_removeClientData
|
|
Packit Service |
37472d |
*/
|
|
Packit Service |
37472d |
gpointer mwConversation_getClientData(struct mwConversation *conv);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** Remove any associated client data, calling the optional cleanup
|
|
Packit Service |
37472d |
function if one was provided
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
@see mwConversation_setClientData
|
|
Packit Service |
37472d |
@see mwConversation_getClientData
|
|
Packit Service |
37472d |
*/
|
|
Packit Service |
37472d |
void mwConversation_removeClientData(struct mwConversation *conv);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
/** close and destroy the conversation and its backing channel, and
|
|
Packit Service |
37472d |
call the optional client data cleanup function */
|
|
Packit Service |
37472d |
void mwConversation_free(struct mwConversation *conv);
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#ifdef __cplusplus
|
|
Packit Service |
37472d |
}
|
|
Packit Service |
37472d |
#endif
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
|
|
Packit Service |
37472d |
#endif /* _MW_SRVC_IM_H */
|