meanwhile 1.1.1
Data Structures | Macros | Enumerations | Functions
mw_srvc_im.h File Reference

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

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

Go to the source code of this file.

Data Structures

struct  mwImHandler
 IM Service Handler. More...
 

Macros

#define mwConversation_isClosed(conv)    mwConversation_isState((conv), mwConversation_CLOSED)
 
#define mwConversation_isOpen(conv)    mwConversation_isState((conv), mwConversation_OPEN)
 
#define mwConversation_isPending(conv)    mwConversation_isState((conv), mwConversation_PENDING)
 
#define mwConversation_isState(conv, state)    (mwConversation_getState(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 mwServiceImmwConversation_getService (struct mwConversation *conv)
 
enum mwConversationState mwConversation_getState (struct mwConversation *conv)
 get the state of a conversation
 
struct mwIdBlockmwConversation_getTarget (struct mwConversation *conv)
 ID for conversation partner.
 
struct mwLoginInfomwConversation_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 mwConversationmwServiceIm_findConversation (struct mwServiceIm *srvc, struct mwIdBlock *target)
 reference an existing conversation to target
 
enum mwImClientType mwServiceIm_getClientType (struct mwServiceIm *srvc)
 
struct mwConversationmwServiceIm_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 mwImHandlermwServiceIm_getHandler (struct mwServiceIm *srvc)
 
struct mwServiceImmwServiceIm_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)     mwConversation_isState((conv), mwConversation_CLOSED)

◆ mwConversation_isOpen

#define mwConversation_isOpen ( conv)     mwConversation_isState((conv), mwConversation_OPEN)

◆ mwConversation_isPending

#define mwConversation_isPending ( conv)     mwConversation_isState((conv), mwConversation_PENDING)

◆ mwConversation_isState

#define mwConversation_isState ( conv,
state )    (mwConversation_getState(conv) == (state))

◆ mwService_IM

#define mwService_IM   0x00001000

Enumeration Type Documentation

◆ 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

Enumerator
mwImClient_PLAIN 

text, typing

mwImClient_NOTESBUDDY 

adds html, subject, mime

mwImClient_PRECONF 

pre-conference, legacy

mwImClient_UNKNOWN 

trouble determining type

◆ 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

◆ 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

◆ mwConversation_getClientData()

gpointer mwConversation_getClientData ( struct mwConversation * conv)

Reference associated client data.

See also
mwConversation_setClientData
mwConversation_removeClientData

◆ mwConversation_getClientType()

enum mwImClientType mwConversation_getClientType ( struct mwConversation * conv)

◆ mwConversation_getService()

struct mwServiceIm * mwConversation_getService ( struct mwConversation * conv)
Returns
owning service for a conversation

◆ mwConversation_getState()

enum mwConversationState mwConversation_getState ( struct mwConversation * conv)

◆ mwConversation_getTarget()

struct mwIdBlock * mwConversation_getTarget ( struct mwConversation * conv)

ID for conversation partner.

◆ mwConversation_getTargetInfo()

struct mwLoginInfo * mwConversation_getTargetInfo ( struct mwConversation * conv)

login information for conversation partner.

returns NULL if conversation is not OPEN

◆ mwConversation_isEncrypted()

gboolean mwConversation_isEncrypted ( struct mwConversation * conv)

determine whether outgoing messages are being encrypted

◆ 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

◆ mwConversation_removeClientData()

void mwConversation_removeClientData ( struct mwConversation * conv)

Remove any associated client data, calling the optional cleanup function if one was provided.

See also
mwConversation_setClientData
mwConversation_getClientData

◆ mwConversation_send()

int mwConversation_send ( struct mwConversation * conv,
enum mwImSendType type,
gconstpointer send )

send a message over an open conversation

◆ mwConversation_setClientData()

void mwConversation_setClientData ( struct mwConversation * conv,
gpointer data,
GDestroyNotify clean )

Associates client data with a conversation.

If there is existing data, it will not have its cleanup function called.

See also
mwConversation_getClientData
mwConversation_removeClientData

◆ mwConversation_setEncrypted()

void mwConversation_setEncrypted ( struct mwConversation * conv,
gboolean useCipher )

set whether outgoing messages should be encrypted using the negotiated cipher, if any

◆ mwConversation_supports()

gboolean mwConversation_supports ( struct mwConversation * conv,
enum mwImSendType type )

determine whether a conversation supports the given message type

◆ mwServiceIm_findConversation()

struct mwConversation * mwServiceIm_findConversation ( struct mwServiceIm * srvc,
struct mwIdBlock * target )

reference an existing conversation to target

◆ mwServiceIm_getClientType()

enum mwImClientType mwServiceIm_getClientType ( struct mwServiceIm * srvc)

◆ mwServiceIm_getConversation()

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

◆ mwServiceIm_getHandler()

struct mwImHandler * mwServiceIm_getHandler ( struct mwServiceIm * srvc)

◆ mwServiceIm_new()

struct mwServiceIm * mwServiceIm_new ( struct mwSession * session,
struct mwImHandler * handler )

◆ mwServiceIm_setClientType()

void mwServiceIm_setClientType ( struct mwServiceIm * srvc,
enum mwImClientType type )

Set the default client type for the service.

Newly created conversations will attempt to meet this level of functionality first.

Parameters
srvcthe IM service
typethe send type to enable/disable

◆ mwServiceIm_supports()

gboolean mwServiceIm_supports ( struct mwServiceIm * srvc,
enum mwImSendType type )

determine if the conversations created from this service will support a given send type