mw_srvc_im.h(3)

NAME
mw_srvc_im.h -

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.

SYNOPSIS

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

  Data Structures
struct mwImHandler
IM Service Handler.

  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 }
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.

  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

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

Author

Generated automatically by Doxygen for meanwhile from the source code.