mw_srvc_im.h File Reference


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.

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

Go to the source code of this file.

Data Structures

struct  mwImHandler
 IM Service Handler. More...

Defines

#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
}
 
See also:
mwConversation_getState
More...
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)
mwServiceImmwConversation_getService (struct mwConversation *conv)
 
Returns:
owning service for a conversation

enum mwConversationState mwConversation_getState (struct mwConversation *conv)
 get the state of a conversation
mwIdBlockmwConversation_getTarget (struct mwConversation *conv)
 ID for conversation partner.
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
mwConversationmwServiceIm_findConversation (struct mwServiceIm *srvc, struct mwIdBlock *target)
 reference an existing conversation to target
enum mwImClientType mwServiceIm_getClientType (struct mwServiceIm *srvc)
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
mwImHandlermwServiceIm_getHandler (struct mwServiceIm *srvc)
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


Define Documentation

#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


Enumeration Type Documentation

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

enum mwImClientType

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

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

void mwConversation_close ( struct mwConversation conv,
guint32  err 
)

close a conversation.

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

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.

See also:
mwConversation_setClientData

mwConversation_removeClientData

enum mwImClientType mwConversation_getClientType ( struct mwConversation conv  ) 

struct mwServiceIm* mwConversation_getService ( struct mwConversation conv  )  [read]

Returns:
owning service for a conversation

enum mwConversationState mwConversation_getState ( struct mwConversation conv  ) 

get the state of a conversation

See also:
mwConversation_isOpen

mwConversation_isClosed

mwConversation_isPending

struct mwIdBlock* mwConversation_getTarget ( struct mwConversation conv  )  [read]

ID for conversation partner.

struct mwLoginInfo* mwConversation_getTargetInfo ( struct mwConversation conv  )  [read]

login information for conversation partner.

returns NULL if conversation is not OPEN

gboolean mwConversation_isEncrypted ( struct mwConversation conv  ) 

determine whether outgoing messages are being encrypted

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

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

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.

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

See also:
mwConversation_getClientData

mwConversation_removeClientData

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 
) [read]

reference an existing conversation to target

enum mwImClientType mwServiceIm_getClientType ( struct mwServiceIm srvc  ) 

struct mwConversation* mwServiceIm_getConversation ( struct mwServiceIm srvc,
struct mwIdBlock target 
) [read]

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  )  [read]

struct mwServiceIm* mwServiceIm_new ( struct mwSession session,
struct mwImHandler handler 
) [read]

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:
srvc the IM service
type the send type to enable/disable

gboolean mwServiceIm_supports ( struct mwServiceIm srvc,
enum mwImSendType  type 
)

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


Generated on Wed May 23 23:43:24 2007 for meanwhile by  doxygen 1.5.2