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)
#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

## 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 | ) |

get the state of a conversation

See also
  mwConversation_isOpen
  mwConversation_isClosed
  mwConversation_isPending

## 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

  srvc | the IM service
  type | the 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