Blame src/mw_srvc_im.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_SRVC_IM_H
Packit 16808d
#define _MW_SRVC_IM_H
Packit 16808d
Packit 16808d
Packit 16808d
/** @file mw_srvc_im.h
Packit 16808d
Packit 16808d
    The IM service provides one-on-one communication between
Packit 16808d
    users. Messages sent over conversations may relay different types
Packit 16808d
    of information, in a variety of formats. The basic feature-set
Packit 16808d
    provides plain-text chat with typing notification. More complex
Packit 16808d
    features may be negotiated transparently by setting the IM Client
Packit 16808d
    Type for a conversation, or for the service as a whole.
Packit 16808d
*/
Packit 16808d
Packit 16808d
Packit 16808d
#include <glib.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
/* identifier for the IM service */
Packit 16808d
#define mwService_IM  0x00001000
Packit 16808d
  
Packit 16808d
  
Packit 16808d
/** @struct mwServiceIm
Packit 16808d
Packit 16808d
    An instance of the IM service. This service provides simple
Packit 16808d
    instant messaging functionality */
Packit 16808d
struct mwServiceIm;
Packit 16808d
Packit 16808d
Packit 16808d
/** @struct mwConversation
Packit 16808d
Packit 16808d
    A conversation between the local service and a single other user */
Packit 16808d
struct mwConversation;
Packit 16808d
Packit 16808d
Packit 16808d
enum mwImClientType {
Packit 16808d
  mwImClient_PLAIN       = 0x00000001,  /**< text, typing */
Packit 16808d
  mwImClient_NOTESBUDDY  = 0x00033453,  /**< adds html, subject, mime */
Packit 16808d
  mwImClient_PRECONF     = 0x00000019,  /**< pre-conference, legacy */
Packit 16808d
  mwImClient_UNKNOWN     = 0xffffffff,  /**< trouble determining type */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
/**
Packit 16808d
   Types of supported messages. When a conversation is created, the
Packit 16808d
   least common denominator of features between either side of the
Packit 16808d
   conversation (based on what features are available in the IM
Packit 16808d
   service itself) becomes the set of supported features for that
Packit 16808d
   conversation. At any point, the feature set for the service may
Packit 16808d
   change, without affecting any existing conversations.
Packit 16808d
Packit 16808d
   @see mwServiceIm_supports
Packit 16808d
   @see mwServiceIm_setSupported
Packit 16808d
   @see mwConversation_supports
Packit 16808d
   @see mwConversation_send
Packit 16808d
   @see mwServiceImHandler::conversation_recv
Packit 16808d
 */
Packit 16808d
enum mwImSendType {
Packit 16808d
  mwImSend_PLAIN,   /**< char *, plain-text message */
Packit 16808d
  mwImSend_TYPING,  /**< gboolean, typing status */
Packit 16808d
  mwImSend_HTML,    /**< char *, HTML formatted message (NOTESBUDDY) */
Packit 16808d
  mwImSend_SUBJECT, /**< char *, conversation subject (NOTESBUDDY) */
Packit 16808d
  mwImSend_MIME,    /**< char *, MIME-encoded message (NOTESBUDDY) */
Packit 16808d
  mwImSend_TIMESTAMP, /**< char *, YYYY:MM:DD:HH:mm:SS format (NOTESBUDDY) */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
Packit 16808d
/** @see mwConversation_getState */
Packit 16808d
enum mwConversationState {
Packit 16808d
  mwConversation_CLOSED,   /**< conversation is not open */
Packit 16808d
  mwConversation_PENDING,  /**< conversation is opening */
Packit 16808d
  mwConversation_OPEN,     /**< conversation is open */
Packit 16808d
  mwConversation_UNKNOWN,  /**< unknown state */
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
#define mwConversation_isState(conv, state) \
Packit 16808d
  (mwConversation_getState(conv) == (state))
Packit 16808d
Packit 16808d
#define mwConversation_isClosed(conv) \
Packit 16808d
  mwConversation_isState((conv), mwConversation_CLOSED)
Packit 16808d
Packit 16808d
#define mwConversation_isPending(conv) \
Packit 16808d
  mwConversation_isState((conv), mwConversation_PENDING)
Packit 16808d
Packit 16808d
#define mwConversation_isOpen(conv) \
Packit 16808d
  mwConversation_isState((conv), mwConversation_OPEN)
Packit 16808d
Packit 16808d
Packit 16808d
Packit 16808d
/** IM Service Handler. Provides functions for events triggered from an
Packit 16808d
    IM service instance. */
Packit 16808d
struct mwImHandler {
Packit 16808d
Packit 16808d
  /** A conversation has been successfully opened */
Packit 16808d
  void (*conversation_opened)(struct mwConversation *conv);
Packit 16808d
Packit 16808d
  /** A conversation has been closed */
Packit 16808d
  void (*conversation_closed)(struct mwConversation *conv, guint32 err);
Packit 16808d
  
Packit 16808d
  /** A message has been received on a conversation */
Packit 16808d
  void (*conversation_recv)(struct mwConversation *conv,
Packit 16808d
			    enum mwImSendType type, gconstpointer msg);
Packit 16808d
Packit 16808d
  /** Handle a Place invitation. Set this to NULL and we should end up
Packit 16808d
      receiving a conference invitation instead. */
Packit 16808d
  void (*place_invite)(struct mwConversation *conv,
Packit 16808d
		       const char *message,
Packit 16808d
		       const char *title, const char *name);
Packit 16808d
Packit 16808d
  /** optional. called from mwService_free */
Packit 16808d
  void (*clear)(struct mwServiceIm *srvc);
Packit 16808d
};
Packit 16808d
Packit 16808d
Packit 16808d
struct mwServiceIm *mwServiceIm_new(struct mwSession *session,
Packit 16808d
				    struct mwImHandler *handler);
Packit 16808d
Packit 16808d
Packit 16808d
struct mwImHandler *mwServiceIm_getHandler(struct mwServiceIm *srvc);
Packit 16808d
Packit 16808d
Packit 16808d
/** reference an existing conversation to target, or create a new
Packit 16808d
    conversation to target if one does not already exist */
Packit 16808d
struct mwConversation *mwServiceIm_getConversation(struct mwServiceIm *srvc,
Packit 16808d
						   struct mwIdBlock *target);
Packit 16808d
Packit 16808d
Packit 16808d
/** reference an existing conversation to target */
Packit 16808d
struct mwConversation *mwServiceIm_findConversation(struct mwServiceIm *srvc,
Packit 16808d
						    struct mwIdBlock *target);
Packit 16808d
Packit 16808d
Packit 16808d
/** determine if the conversations created from this service will
Packit 16808d
    support a given send type */
Packit 16808d
gboolean mwServiceIm_supports(struct mwServiceIm *srvc,
Packit 16808d
			      enum mwImSendType type);
Packit 16808d
Packit 16808d
Packit 16808d
/** Set the default client type for the service. Newly created
Packit 16808d
    conversations will attempt to meet this level of functionality
Packit 16808d
    first.
Packit 16808d
Packit 16808d
    @param srvc       the IM service
Packit 16808d
    @param type       the send type to enable/disable
Packit 16808d
*/
Packit 16808d
void mwServiceIm_setClientType(struct mwServiceIm *srvc,
Packit 16808d
			       enum mwImClientType type);
Packit 16808d
Packit 16808d
Packit 16808d
enum mwImClientType mwServiceIm_getClientType(struct mwServiceIm *srvc);
Packit 16808d
Packit 16808d
Packit 16808d
/** attempt to open a conversation. If the conversation was not
Packit 16808d
    already open and it is accepted,
Packit 16808d
    mwServiceImHandler::conversation_opened will be triggered. Upon
Packit 16808d
    failure, mwServiceImHandler::conversation_closed will be
Packit 16808d
    triggered */
Packit 16808d
void mwConversation_open(struct mwConversation *conv);
Packit 16808d
Packit 16808d
Packit 16808d
/** close a conversation. If the conversation was not already closed,
Packit 16808d
    mwServiceImHandler::conversation_closed will be triggered */
Packit 16808d
void mwConversation_close(struct mwConversation *conv, guint32 err);
Packit 16808d
Packit 16808d
Packit 16808d
/** determine whether a conversation supports the given message type */
Packit 16808d
gboolean mwConversation_supports(struct mwConversation *conv,
Packit 16808d
				 enum mwImSendType type);
Packit 16808d
Packit 16808d
Packit 16808d
enum mwImClientType mwConversation_getClientType(struct mwConversation *conv);
Packit 16808d
Packit 16808d
Packit 16808d
/** get the state of a conversation
Packit 16808d
Packit 16808d
    @see mwConversation_isOpen
Packit 16808d
    @see mwConversation_isClosed
Packit 16808d
    @see mwConversation_isPending
Packit 16808d
*/
Packit 16808d
enum mwConversationState mwConversation_getState(struct mwConversation *conv);
Packit 16808d
Packit 16808d
Packit 16808d
/** send a message over an open conversation */
Packit 16808d
int mwConversation_send(struct mwConversation *conv,
Packit 16808d
			enum mwImSendType type, gconstpointer send);
Packit 16808d
Packit 16808d
Packit 16808d
/** @returns owning service for a conversation */
Packit 16808d
struct mwServiceIm *mwConversation_getService(struct mwConversation *conv);
Packit 16808d
Packit 16808d
Packit 16808d
/** login information for conversation partner. returns NULL if conversation 
Packit 16808d
    is not OPEN */
Packit 16808d
struct mwLoginInfo *mwConversation_getTargetInfo(struct mwConversation *conv);
Packit 16808d
Packit 16808d
Packit 16808d
/** ID for conversation partner */
Packit 16808d
struct mwIdBlock *mwConversation_getTarget(struct mwConversation *conv);
Packit 16808d
Packit 16808d
Packit 16808d
/** set whether outgoing messages should be encrypted using the
Packit 16808d
    negotiated cipher, if any */
Packit 16808d
void mwConversation_setEncrypted(struct mwConversation *conv,
Packit 16808d
				 gboolean useCipher);
Packit 16808d
Packit 16808d
Packit 16808d
/** determine whether outgoing messages are being encrypted */
Packit 16808d
gboolean mwConversation_isEncrypted(struct mwConversation *conv);
Packit 16808d
Packit 16808d
Packit 16808d
/** Associates client data with a conversation. If there is existing data,
Packit 16808d
    it will not have its cleanup function called.
Packit 16808d
Packit 16808d
    @see mwConversation_getClientData
Packit 16808d
    @see mwConversation_removeClientData
Packit 16808d
*/
Packit 16808d
void mwConversation_setClientData(struct mwConversation *conv,
Packit 16808d
				  gpointer data, GDestroyNotify clean);
Packit 16808d
Packit 16808d
Packit 16808d
/** Reference associated client data
Packit 16808d
Packit 16808d
    @see mwConversation_setClientData
Packit 16808d
    @see mwConversation_removeClientData
Packit 16808d
 */
Packit 16808d
gpointer mwConversation_getClientData(struct mwConversation *conv);
Packit 16808d
Packit 16808d
Packit 16808d
/** Remove any associated client data, calling the optional cleanup
Packit 16808d
    function if one was provided
Packit 16808d
Packit 16808d
    @see mwConversation_setClientData
Packit 16808d
    @see mwConversation_getClientData
Packit 16808d
*/
Packit 16808d
void mwConversation_removeClientData(struct mwConversation *conv);
Packit 16808d
Packit 16808d
Packit 16808d
/** close and destroy the conversation and its backing channel, and
Packit 16808d
    call the optional client data cleanup function */
Packit 16808d
void mwConversation_free(struct mwConversation *conv);
Packit 16808d
Packit 16808d
Packit 16808d
#ifdef __cplusplus
Packit 16808d
}
Packit 16808d
#endif
Packit 16808d
Packit 16808d
Packit 16808d
#endif /* _MW_SRVC_IM_H */