The IM service provides one-on-one communication between users. More...

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

Data Structures
struct	mwImHandler
	IM Service Handler. More...

Macros
#define	mwConversation_isClosed(conv)
#define	mwConversation_isOpen(conv)
#define	mwConversation_isPending(conv)
#define	mwConversation_isState(conv, state)
#define	mwService_IM 0x00001000

Enumerations
enum	mwConversationState { mwConversation_CLOSED , mwConversation_PENDING , mwConversation_OPEN , mwConversation_UNKNOWN }
enum	mwImClientType { mwImClient_PLAIN = 0x00000001 , mwImClient_NOTESBUDDY = 0x00033453 , mwImClient_PRECONF = 0x00000019 , mwImClient_UNKNOWN = 0xffffffff }
enum	mwImSendType { mwImSend_PLAIN , mwImSend_TYPING , mwImSend_HTML , mwImSend_SUBJECT , mwImSend_MIME , mwImSend_TIMESTAMP }
	Types of supported messages. More...

Functions
void	mwConversation_close (struct mwConversation *conv, guint32 err)
	close a conversation.
void	mwConversation_free (struct mwConversation *conv)
	close and destroy the conversation and its backing channel, and call the optional client data cleanup function
gpointer	mwConversation_getClientData (struct mwConversation *conv)
	Reference associated client data.
enum mwImClientType	mwConversation_getClientType (struct mwConversation *conv)
struct mwServiceIm *	mwConversation_getService (struct mwConversation *conv)
enum mwConversationState	mwConversation_getState (struct mwConversation *conv)
	get the state of a conversation
struct mwIdBlock *	mwConversation_getTarget (struct mwConversation *conv)
	ID for conversation partner.
struct mwLoginInfo *	mwConversation_getTargetInfo (struct mwConversation *conv)
	login information for conversation partner.
gboolean	mwConversation_isEncrypted (struct mwConversation *conv)
	determine whether outgoing messages are being encrypted
void	mwConversation_open (struct mwConversation *conv)
	attempt to open a conversation.
void	mwConversation_removeClientData (struct mwConversation *conv)
	Remove any associated client data, calling the optional cleanup function if one was provided.
int	mwConversation_send (struct mwConversation *conv, enum mwImSendType type, gconstpointer send)
	send a message over an open conversation
void	mwConversation_setClientData (struct mwConversation *conv, gpointer data, GDestroyNotify clean)
	Associates client data with a conversation.
void	mwConversation_setEncrypted (struct mwConversation *conv, gboolean useCipher)
	set whether outgoing messages should be encrypted using the negotiated cipher, if any
gboolean	mwConversation_supports (struct mwConversation *conv, enum mwImSendType type)
	determine whether a conversation supports the given message type
struct mwConversation *	mwServiceIm_findConversation (struct mwServiceIm srvc, struct mwIdBlock target)
	reference an existing conversation to target
enum mwImClientType	mwServiceIm_getClientType (struct mwServiceIm *srvc)
struct mwConversation *	mwServiceIm_getConversation (struct mwServiceIm srvc, struct mwIdBlock target)
	reference an existing conversation to target, or create a new conversation to target if one does not already exist
struct mwImHandler *	mwServiceIm_getHandler (struct mwServiceIm *srvc)
struct mwServiceIm *	mwServiceIm_new (struct mwSession session, struct mwImHandler handler)
void	mwServiceIm_setClientType (struct mwServiceIm *srvc, enum mwImClientType type)
	Set the default client type for the service.
gboolean	mwServiceIm_supports (struct mwServiceIm *srvc, enum mwImSendType type)
	determine if the conversations created from this service will support a given send type

Detailed Description

The IM service provides one-on-one communication between users.

Messages sent over conversations may relay different types of information, in a variety of formats. The basic feature-set provides plain-text chat with typing notification. More complex features may be negotiated transparently by setting the IM Client Type for a conversation, or for the service as a whole.

Macro Definition Documentation

◆ mwConversation_isClosed

#define mwConversation_isClosed ( conv )

Value:

mwConversation_isState((conv), mwConversation_CLOSED)

mwConversation_isState

#define mwConversation_isState(conv, state)

Definition mw_srvc_im.h:104

mwConversation_CLOSED

@ mwConversation_CLOSED

conversation is not open

Definition mw_srvc_im.h:97

◆ mwConversation_isOpen

#define mwConversation_isOpen ( conv )

Value:

mwConversation_isState((conv), mwConversation_OPEN)

mwConversation_OPEN

@ mwConversation_OPEN

conversation is open

Definition mw_srvc_im.h:99

◆ mwConversation_isPending

#define mwConversation_isPending ( conv )

Value:

mwConversation_isState((conv), mwConversation_PENDING)

mwConversation_PENDING

@ mwConversation_PENDING

conversation is opening

Definition mw_srvc_im.h:98

◆ mwConversation_isState

#define mwConversation_isState	(		conv,
			state )

Value:

(mwConversation_getState(conv) == (state))

mwConversation_getState

enum mwConversationState mwConversation_getState(struct mwConversation *conv)

get the state of a conversation

◆ mwService_IM

#define mwService_IM 0x00001000

Enumeration Type Documentation

◆ mwConversationState

enum mwConversationState

See also: mwConversation_getState

Enumerator
mwConversation_CLOSED	conversation is not open
mwConversation_PENDING	conversation is opening
mwConversation_OPEN	conversation is open
mwConversation_UNKNOWN	unknown state

◆ mwImClientType

enum mwImClientType

Enumerator
mwImClient_PLAIN	text, typing
mwImClient_NOTESBUDDY	adds html, subject, mime
mwImClient_PRECONF	pre-conference, legacy
mwImClient_UNKNOWN	trouble determining type

◆ mwImSendType

enum mwImSendType

Types of supported messages.

When a conversation is created, the least common denominator of features between either side of the conversation (based on what features are available in the IM service itself) becomes the set of supported features for that conversation. At any point, the feature set for the service may change, without affecting any existing conversations.

See also: mwServiceIm_supports; mwServiceIm_setSupported; mwConversation_supports; mwConversation_send; mwServiceImHandler::conversation_recv

Enumerator
mwImSend_PLAIN	char *, plain-text message
mwImSend_TYPING	gboolean, typing status
mwImSend_HTML	char *, HTML formatted message (NOTESBUDDY)
mwImSend_SUBJECT	char *, conversation subject (NOTESBUDDY)
mwImSend_MIME	char *, MIME-encoded message (NOTESBUDDY)
mwImSend_TIMESTAMP	char *, YYYY:MM:DD:HH:mm:SS format (NOTESBUDDY)

Function Documentation

◆ mwConversation_close()

void mwConversation_close	(	struct mwConversation *	conv,
		guint32	err )

close a conversation.

If the conversation was not already closed, mwServiceImHandler::conversation_closed will be triggered

References mwConversation_close().

Referenced by mwConversation_close().

◆ mwConversation_free()

void mwConversation_free ( struct mwConversation * conv )

close and destroy the conversation and its backing channel, and call the optional client data cleanup function

References mwConversation_free().

Referenced by mwConversation_free().

◆ mwConversation_getClientData()

gpointer mwConversation_getClientData ( struct mwConversation * conv )

Reference associated client data.

See also: mwConversation_setClientData; mwConversation_removeClientData

References mwConversation_getClientData().

Referenced by mwConversation_getClientData().

◆ mwConversation_getClientType()

enum mwImClientType mwConversation_getClientType ( struct mwConversation * conv )

References mwConversation_getClientType().

Referenced by mwConversation_getClientType().

◆ mwConversation_getService()

struct mwServiceIm * mwConversation_getService ( struct mwConversation * conv )

Returns: owning service for a conversation

References mwConversation_getService().

Referenced by mwConversation_getService().

◆ mwConversation_getState()

enum mwConversationState mwConversation_getState ( struct mwConversation * conv )

get the state of a conversation

See also: mwConversation_isOpen; mwConversation_isClosed; mwConversation_isPending

References mwConversation_getState().

Referenced by mwConversation_getState().

◆ mwConversation_getTarget()

struct mwIdBlock * mwConversation_getTarget ( struct mwConversation * conv )

ID for conversation partner.

References mwConversation_getTarget().

Referenced by mwConversation_getTarget().

◆ mwConversation_getTargetInfo()

struct mwLoginInfo * mwConversation_getTargetInfo ( struct mwConversation * conv )

login information for conversation partner.

returns NULL if conversation is not OPEN

References mwConversation_getTargetInfo().

Referenced by mwConversation_getTargetInfo().

◆ mwConversation_isEncrypted()

gboolean mwConversation_isEncrypted ( struct mwConversation * conv )

determine whether outgoing messages are being encrypted

References mwConversation_isEncrypted().

Referenced by mwConversation_isEncrypted().

◆ mwConversation_open()

void mwConversation_open ( struct mwConversation * conv )

attempt to open a conversation.

If the conversation was not already open and it is accepted, mwServiceImHandler::conversation_opened will be triggered. Upon failure, mwServiceImHandler::conversation_closed will be triggered

References mwConversation_open().

Referenced by mwConversation_open().