WockyMuc

WockyMuc — multi-user chat rooms

Synopsis

#include <wocky/wocky.h>

enum                WockyMucStatusCode;
enum                WockyMucRole;
enum                WockyMucAffiliation;
enum                WockyMucFeature;
enum                WockyMucMsgType;
enum                WockyMucMsgState;
enum                WockyMucState;
                    WockyMucMember;
struct              WockyMuc;
struct              WockyMucClass;
void                wocky_muc_disco_info_async          (WockyMuc *muc,
                                                         GAsyncReadyCallback callback,
                                                         GCancellable *cancel,
                                                         gpointer data);
gboolean            wocky_muc_disco_info_finish         (WockyMuc *muc,
                                                         GAsyncResult *res,
                                                         GError **error);
WockyStanza *       wocky_muc_create_presence           (WockyMuc *muc,
                                                         WockyStanzaSubType type,
                                                         const gchar *status);
void                wocky_muc_join                      (WockyMuc *muc,
                                                         GCancellable *cancel);
const gchar *       wocky_muc_jid                       (WockyMuc *muc);
const gchar *       wocky_muc_user                      (WockyMuc *muc);
WockyMucRole        wocky_muc_role                      (WockyMuc *muc);
WockyMucAffiliation wocky_muc_affiliation               (WockyMuc *muc);
GHashTable *        wocky_muc_members                   (WockyMuc *muc);
WockyMucState       wocky_muc_get_state                 (WockyMuc *muc);

Object Hierarchy

  GFlags
   +----WockyMucStatusCode
  GEnum
   +----WockyMucRole
  GEnum
   +----WockyMucAffiliation
  GFlags
   +----WockyMucFeature
  GEnum
   +----WockyMucMsgType
  GEnum
   +----WockyMucMsgState
  GEnum
   +----WockyMucState
  GObject
   +----WockyMuc

Properties

  "affiliation"              WockyMucAffiliation   : Read
  "category"                 gchar*                : Read
  "description"              gchar*                : Read
  "jid"                      gchar*                : Read / Write
  "muc-flags"                gulong                : Read
  "name"                     gchar*                : Read
  "nickname"                 gchar*                : Read
  "password"                 gchar*                : Read / Write
  "porter"                   WockyPorter*          : Read / Write / Construct Only
  "reserved-nick"            gchar*                : Read
  "role"                     guint                 : Read
  "room"                     gchar*                : Read
  "service"                  gchar*                : Read
  "status-message"           gchar*                : Read
  "type"                     gchar*                : Read
  "user"                     gchar*                : Read / Write / Construct Only

Signals

  "error"                                          : Run Last
  "fill-presence"                                  : Run Last
  "joined"                                         : Run Last
  "left"                                           : Run Last
  "message"                                        : Run Last
  "message-error"                                  : Run Last
  "nick-change"                                    : Run Last
  "own-presence"                                   : Run Last
  "parted"                                         : Run Last
  "permissions"                                    : Run Last
  "presence"                                       : Run Last

Description

Represents a multi-user chat room. Because the MUC protocol is so terrible, you will find yourself consulting XEP-0045 and shedding more than a few tears while using this class.

Details

enum WockyMucStatusCode

typedef enum {
  WOCKY_MUC_CODE_UNKNOWN = 0,
  WOCKY_MUC_CODE_ONYMOUS = 1 << 0,
  WOCKY_MUC_CODE_AF_CHANGE_OOB = 1 << 1,
  WOCKY_MUC_CODE_CFG_SHOW_UNAVAILABLE = 1 << 2,
  WOCKY_MUC_CODE_CFG_HIDE_UNAVAILABLE = 1 << 3,
  WOCKY_MUC_CODE_CFG_NONPRIVACY = 1 << 4,
  WOCKY_MUC_CODE_OWN_PRESENCE = 1 << 5,
  WOCKY_MUC_CODE_CFG_LOGGING_ENABLED = 1 << 6,
  WOCKY_MUC_CODE_CFG_LOGGING_DISABLED = 1 << 7,
  WOCKY_MUC_CODE_CFG_ONYMOUS = 1 << 8,
  WOCKY_MUC_CODE_CFG_SEMIONYMOUS = 1 << 9,
  WOCKY_MUC_CODE_CFG_ANONYMOUS = 1 << 10,
  WOCKY_MUC_CODE_NEW_ROOM = 1 << 11,
  WOCKY_MUC_CODE_NICK_CHANGE_FORCED = 1 << 12,
  WOCKY_MUC_CODE_BANNED = 1 << 13,
  WOCKY_MUC_CODE_NICK_CHANGE_USER = 1 << 14,
  WOCKY_MUC_CODE_KICKED = 1 << 15,
  WOCKY_MUC_CODE_KICKED_AFFILIATION = 1 << 16,
  WOCKY_MUC_CODE_KICKED_ROOM_PRIVATISED = 1 << 17,
  WOCKY_MUC_CODE_KICKED_SHUTDOWN = 1 << 18,
} WockyMucStatusCode;

MUC status codes, as defined by XEP-0045 §15.6.

WOCKY_MUC_CODE_UNKNOWN

Unknown code

WOCKY_MUC_CODE_ONYMOUS

Room entered is not anonymous

WOCKY_MUC_CODE_AF_CHANGE_OOB

Affiliation changed when not present

WOCKY_MUC_CODE_CFG_SHOW_UNAVAILABLE

Unavailable members visible

WOCKY_MUC_CODE_CFG_HIDE_UNAVAILABLE

Unavailable members invisible

WOCKY_MUC_CODE_CFG_NONPRIVACY

Non-privacy config change

WOCKY_MUC_CODE_OWN_PRESENCE

User's own presence

WOCKY_MUC_CODE_CFG_LOGGING_ENABLED

Logging enabled

WOCKY_MUC_CODE_CFG_LOGGING_DISABLED

Logging disabled

WOCKY_MUC_CODE_CFG_ONYMOUS

Room is now non-anonymous

WOCKY_MUC_CODE_CFG_SEMIONYMOUS

Room is now semi-anonymous

WOCKY_MUC_CODE_CFG_ANONYMOUS

Room is now fully-anonymous

WOCKY_MUC_CODE_NEW_ROOM

Room created (eg by joining)

WOCKY_MUC_CODE_NICK_CHANGE_FORCED

Service enforced nick change

WOCKY_MUC_CODE_BANNED

User has been banned

WOCKY_MUC_CODE_NICK_CHANGE_USER

User's nick changed

WOCKY_MUC_CODE_KICKED

Kicked from the room

WOCKY_MUC_CODE_KICKED_AFFILIATION

Kicked (affiliation change)

WOCKY_MUC_CODE_KICKED_ROOM_PRIVATISED

Kicked (room is now members-only)

WOCKY_MUC_CODE_KICKED_SHUTDOWN

Kicked (shutdown)

enum WockyMucRole

typedef enum {
  WOCKY_MUC_ROLE_NONE = 0,
  WOCKY_MUC_ROLE_VISITOR,
  WOCKY_MUC_ROLE_PARTICIPANT,
  WOCKY_MUC_ROLE_MODERATOR
} WockyMucRole;

WockyMuc roles as described in XEP-0045 §5.1.

WOCKY_MUC_ROLE_NONE

no role

WOCKY_MUC_ROLE_VISITOR

visitor role

WOCKY_MUC_ROLE_PARTICIPANT

participant role

WOCKY_MUC_ROLE_MODERATOR

moderator role

enum WockyMucAffiliation

typedef enum {
  WOCKY_MUC_AFFILIATION_OUTCAST = -1,
  WOCKY_MUC_AFFILIATION_NONE = 0,
  WOCKY_MUC_AFFILIATION_MEMBER,
  WOCKY_MUC_AFFILIATION_ADMIN,
  WOCKY_MUC_AFFILIATION_OWNER,
} WockyMucAffiliation;

WockyMuc affiliations as described in XEP-0045 §5.2.

WOCKY_MUC_AFFILIATION_OUTCAST

outcast affiliation

WOCKY_MUC_AFFILIATION_NONE

no affiliation

WOCKY_MUC_AFFILIATION_MEMBER

member affiliation

WOCKY_MUC_AFFILIATION_ADMIN

admin affiliation

WOCKY_MUC_AFFILIATION_OWNER

owner affiliation

enum WockyMucFeature

typedef enum {
  WOCKY_MUC_MODERN = 1,
  WOCKY_MUC_FORM_REGISTER = (1 << 1),
  WOCKY_MUC_FORM_ROOMCONFIG = (1 << 2),
  WOCKY_MUC_FORM_ROOMINFO = (1 << 3),
  WOCKY_MUC_HIDDEN = (1 << 4),
  WOCKY_MUC_MEMBERSONLY = (1 << 5),
  WOCKY_MUC_MODERATED = (1 << 6),
  WOCKY_MUC_NONANONYMOUS = (1 << 7),
  WOCKY_MUC_OPEN = (1 << 8),
  WOCKY_MUC_PASSWORDPROTECTED = (1 << 9),
  WOCKY_MUC_PERSISTENT = (1 << 10),
  WOCKY_MUC_PUBLIC = (1 << 11),
  WOCKY_MUC_ROOMS = (1 << 12),
  WOCKY_MUC_SEMIANONYMOUS = (1 << 13),
  WOCKY_MUC_TEMPORARY = (1 << 14),
  WOCKY_MUC_UNMODERATED = (1 << 15),
  WOCKY_MUC_UNSECURED = (1 << 16),
  WOCKY_MUC_OBSOLETE = (1 << 17),
} WockyMucFeature;

WockyMuc feature flags.

WOCKY_MUC_MODERN

the MUC is modern, as documented in XEP-0045

WOCKY_MUC_FORM_REGISTER

the MUC has support for the mucregister FORM_TYPE

WOCKY_MUC_FORM_ROOMCONFIG

the MUC has support for the mucregister FORM_TYPE

WOCKY_MUC_FORM_ROOMINFO

the MUC has support for the mucregister FORM_TYPE

WOCKY_MUC_HIDDEN

the MUC is hidden

WOCKY_MUC_MEMBERSONLY

only members can join this MUC

WOCKY_MUC_MODERATED

the MUC is moderated

WOCKY_MUC_NONANONYMOUS

the MUC is non-anonymous

WOCKY_MUC_OPEN

the MUC is open

WOCKY_MUC_PASSWORDPROTECTED

the MUC is password protected

WOCKY_MUC_PERSISTENT

the MUC is persistent

WOCKY_MUC_PUBLIC

the MUC is public

WOCKY_MUC_ROOMS

the MUC has a list of MUC rooms

WOCKY_MUC_SEMIANONYMOUS

the MUC is semi-anonymous

WOCKY_MUC_TEMPORARY

the MUC is temporary

WOCKY_MUC_UNMODERATED

the MUC is unmoderated

WOCKY_MUC_UNSECURED

the MUC is unsecured

WOCKY_MUC_OBSOLETE

the MUC has obsolete groupchat 1.0 features

enum WockyMucMsgType

typedef enum {
  WOCKY_MUC_MSG_NONE,
  WOCKY_MUC_MSG_NORMAL,
  WOCKY_MUC_MSG_ACTION,
  WOCKY_MUC_MSG_NOTICE,
} WockyMucMsgType;

XMPP MUC message types.

WOCKY_MUC_MSG_NONE

no message type

WOCKY_MUC_MSG_NORMAL

a normal message

WOCKY_MUC_MSG_ACTION

an action message

WOCKY_MUC_MSG_NOTICE

a notice message

enum WockyMucMsgState

typedef enum {
  WOCKY_MUC_MSG_STATE_NONE = -1,
  WOCKY_MUC_MSG_STATE_ACTIVE,
  WOCKY_MUC_MSG_STATE_COMPOSING,
  WOCKY_MUC_MSG_STATE_INACTIVE,
  WOCKY_MUC_MSG_STATE_PAUSED,
} WockyMucMsgState;

XMPP MUC message states as documeted in XEP-0085.

WOCKY_MUC_MSG_STATE_NONE

no message state applies

WOCKY_MUC_MSG_STATE_ACTIVE

the contact in the MUC is active

WOCKY_MUC_MSG_STATE_COMPOSING

the contact in the MUC is composing a message

WOCKY_MUC_MSG_STATE_INACTIVE

the contact in the MUC is inactive

WOCKY_MUC_MSG_STATE_PAUSED

the contact in the MUC has paused composing a message

enum WockyMucState

typedef enum {
  WOCKY_MUC_CREATED = 0,
  WOCKY_MUC_INITIATED,
  WOCKY_MUC_AUTH,
  WOCKY_MUC_JOINED,
  WOCKY_MUC_ENDED,
} WockyMucState;

WockyMuc states.

WOCKY_MUC_CREATED

the WockyMuc has been created

WOCKY_MUC_INITIATED

the MUC has been initiated on the server

WOCKY_MUC_AUTH

the user is authenticating with the MUC

WOCKY_MUC_JOINED

the user has joined the MUC and can chat

WOCKY_MUC_ENDED

the MUC has ended

WockyMucMember

typedef struct {
  gchar *from;   /* room@service/nick     */
  gchar *jid;    /* owner@domain/resource */
  gchar *nick;   /* nick */
  WockyMucRole role;
  WockyMucAffiliation affiliation;
  gchar *status; /* user set status string */
  WockyStanza *presence_stanza;
} WockyMucMember;

gchar *from;

the JID of the member (room@server/nick)

gchar *jid;

the JID of the owner (owner@domain/resource)

gchar *nick;

the nickname of the member

WockyMucRole role;

the WockyMucRole of the member

WockyMucAffiliation affiliation;

the WockyMucAffiliation of the member

gchar *status;

the user set status string

WockyStanza *presence_stanza;

the WockyStanza that was received regarding the member's presence

struct WockyMuc

struct WockyMuc;

struct WockyMucClass

struct WockyMucClass {
};

The class of a WockyMuc.


wocky_muc_disco_info_async ()

void                wocky_muc_disco_info_async          (WockyMuc *muc,
                                                         GAsyncReadyCallback callback,
                                                         GCancellable *cancel,
                                                         gpointer data);

wocky_muc_disco_info_finish ()

gboolean            wocky_muc_disco_info_finish         (WockyMuc *muc,
                                                         GAsyncResult *res,
                                                         GError **error);

wocky_muc_create_presence ()

WockyStanza *       wocky_muc_create_presence           (WockyMuc *muc,
                                                         WockyStanzaSubType type,
                                                         const gchar *status);

wocky_muc_join ()

void                wocky_muc_join                      (WockyMuc *muc,
                                                         GCancellable *cancel);

wocky_muc_jid ()

const gchar *       wocky_muc_jid                       (WockyMuc *muc);

wocky_muc_user ()

const gchar *       wocky_muc_user                      (WockyMuc *muc);

wocky_muc_role ()

WockyMucRole        wocky_muc_role                      (WockyMuc *muc);

wocky_muc_affiliation ()

WockyMucAffiliation wocky_muc_affiliation               (WockyMuc *muc);

wocky_muc_members ()

GHashTable *        wocky_muc_members                   (WockyMuc *muc);

wocky_muc_get_state ()

WockyMucState       wocky_muc_get_state                 (WockyMuc *muc);

Property Details

The "affiliation" property

  "affiliation"              WockyMucAffiliation   : Read

The affiliation of the user with the MUC room.

Default value: WOCKY_MUC_AFFILIATION_NONE


The "category" property

  "category"                 gchar*                : Read

Category of the MUC, usually "conference".

Default value: NULL


The "description" property

  "description"              gchar*                : Read

The long description oof the room.

Default value: NULL


The "jid" property

  "jid"                      gchar*                : Read / Write

Full room@service/nick JID of the MUC room.

Default value: NULL


The "muc-flags" property

  "muc-flags"                gulong                : Read

ORed set of WockyMucFeature MUC property flags.


The "name" property

  "name"                     gchar*                : Read

The human-readable name of the room (usually a short label).

Default value: NULL


The "nickname" property

  "nickname"                 gchar*                : Read

The user's in-room nickname.

Default value: NULL


The "password" property

  "password"                 gchar*                : Read / Write

User's MUC room password.

Default value: NULL


The "porter" property

  "porter"                   WockyPorter*          : Read / Write / Construct Only

The WockyPorter instance doing all the actual XMPP interaction.


The "reserved-nick" property

  "reserved-nick"            gchar*                : Read

The user's reserved in-room nickname, if any.

Default value: NULL


The "role" property

  "role"                     guint                 : Read

The role (WockyMucRole) of the user in the MUC room.

Allowed values: <= 3

Default value: 0


The "room" property

  "room"                     gchar*                : Read

The node part of the MUC room JID.

Default value: NULL


The "service" property

  "service"                  gchar*                : Read

The service (domain) part of the MUC JID.

Default value: NULL


The "status-message" property

  "status-message"           gchar*                : Read

User's MUC status message.

Default value: NULL


The "type" property

  "type"                     gchar*                : Read

Type of the MUC, eg "text".

Default value: NULL


The "user" property

  "user"                     gchar*                : Read / Write / Construct Only

Full JID of the user (node@domain/resource) who is connecting.

Default value: NULL

Signal Details

The "error" signal

void                user_function                      (WockyMuc          *muc,
                                                        WockyStanza       *stanza,
                                                        WockyXmppErrorType error_type,
                                                        GError            *error,
                                                        gpointer           user_data)       : Run Last

Emitted when a presence error is received from the MUC, which is generally in response to trying to join the MUC.

muc :

the MUC

stanza :

the presence stanza

error_type :

the type of error

error :

an error in domain WOCKY_XMPP_ERROR, whose message (if not NULL) is a human-readable message from the server

user_data :

user data set when the signal handler was connected.

The "fill-presence" signal

void                user_function                      (WockyMuc    *wockymuc,
                                                        WockyStanza *arg1,
                                                        gpointer     user_data)      : Run Last

The "joined" signal

void                user_function                      (WockyMuc    *muc,
                                                        WockyStanza *stanza,
                                                        guint        codes,
                                                        gpointer     user_data)      : Run Last

Emitted when the local user successfully joins muc.

muc :

the MUC

stanza :

the presence stanza

codes :

bitwise OR of WockyMucStatusCode flags with miscellaneous information about the MUC

user_data :

user data set when the signal handler was connected.

The "left" signal

void                user_function                      (WockyMuc    *muc,
                                                        WockyStanza *stanza,
                                                        guint        codes,
                                                        gpointer     member,
                                                        gchar       *actor,
                                                        gchar       *reason,
                                                        gchar       *message,
                                                        gpointer     user_data)      : Run Last

Emitted when another participant leaves, or is kicked from, the MUC

muc :

the MUC

stanza :

the presence stanza

codes :

bitwise OR of WockyMucStatusCode flags describing why member left the MUC

member :

the (now ex-)member of the MUC who left

actor :

if member was removed from the MUC by another participant, that participant's JID

reason :

if member was removed from the MUC by another participant, a human-readable reason given by that participant

message :

a parting message provided by member, or NULL

user_data :

user data set when the signal handler was connected.

The "message" signal

void                user_function                      (WockyMuc        *muc,
                                                        WockyStanza     *stanza,
                                                        WockyMucMsgType  message_type,
                                                        gchar           *id,
                                                        GDateTime       *timestamp,
                                                        gpointer         sender,
                                                        gchar           *body,
                                                        gchar           *subject,
                                                        WockyMucMsgState state,
                                                        gpointer         user_data)         : Run Last

Emitted when a non-error message stanza is received. This may indicate:

  • if body is not NULL, a message sent by sender to the MUC;
  • or, if subject is not NULL, sender changed the subject of the MUC;
  • additionally, that sender is typing, or maybe stopped typing, depending on state.

muc :

the MUC

stanza :

the incoming message stanza

message_type :

the message's type

id :

the stanza's identifier (which may be NULL if neither the sender nor the MUC specified one)

timestamp :

for messages received as scrollback when joining the MUC, the time the message was sent; NULL for messages received while in the MUC

sender :

a WockyMucMember struct describing the sender of the message

body :

the body of the message, or NULL

subject :

the new subject for the MUC, or NULL

state :

whether sender is currently typing.

user_data :

user data set when the signal handler was connected.

The "message-error" signal

void                user_function                      (WockyMuc          *muc,
                                                        WockyStanza       *stanza,
                                                        WockyMucMsgType    message_type,
                                                        gchar             *id,
                                                        GDateTime         *timestamp,
                                                        gpointer           member,
                                                        gchar             *body,
                                                        WockyXmppErrorType error_type,
                                                        GError            *error,
                                                        gpointer           user_data)         : Run Last

Emitted when we receive an error from the MUC in response to sending a message stanza to the MUC.

muc :

the MUC

stanza :

the incoming WOCKY_STANZA_SUB_TYPE_ERROR message

message_type :

the type of the message which was rejected

id :

the identifier for the original message and this error (which may be NULL)

timestamp :

the timestamp attached to the original message, which is probably NULL because timestamps are only attached to scrollback messages

member :

a WockyMucMember struct describing the sender of the original message (which is, we presume, us)

body :

the body of the message which failed to send

error_type :

the type of error

error :

an error in domain WOCKY_XMPP_ERROR, whose message (if not NULL) is a human-readable message from the server

user_data :

user data set when the signal handler was connected.

The "nick-change" signal

void                user_function                      (WockyMuc    *wockymuc,
                                                        WockyStanza *arg1,
                                                        guint        arg2,
                                                        gpointer     user_data)      : Run Last

The "own-presence" signal

void                user_function                      (WockyMuc    *wockymuc,
                                                        WockyStanza *arg1,
                                                        guint        arg2,
                                                        gpointer     user_data)      : Run Last

The "parted" signal

void                user_function                      (WockyMuc    *muc,
                                                        WockyStanza *stanza,
                                                        guint        codes,
                                                        gchar       *actor,
                                                        gchar       *reason,
                                                        gchar       *message,
                                                        gpointer     user_data)      : Run Last

Emitted when the local user leaves the MUC, whether by choice or by force.

muc :

the MUC

stanza :

the presence stanza

codes :

bitwise OR of WockyMucStatusCode flags describing why the user left the MUC

actor :

if the user was removed from the MUC by another participant, that participant's JID

reason :

if the user was removed from the MUC by another participant, a human-readable reason given by that participant

message :

a parting message we provided to other participants, or NULL

user_data :

user data set when the signal handler was connected.

The "permissions" signal

void                user_function                      (WockyMuc    *muc,
                                                        WockyStanza *stanza,
                                                        guint        codes,
                                                        gchar       *actor_jid,
                                                        gchar       *reason,
                                                        gpointer     user_data)      : Run Last

Emitted when our permissions within the MUC are changed.

muc :

the muc

stanza :

the presence stanza heralding the change

codes :

bitwise OR of WockyMucStatusCode flags

actor_jid :

the JID of the user who changed our permissions, or NULL

reason :

a human-readable reason for the change, or NULL

user_data :

user data set when the signal handler was connected.

The "presence" signal

void                user_function                      (WockyMuc    *wockymuc,
                                                        WockyStanza *arg1,
                                                        guint        arg2,
                                                        gpointer     arg3,
                                                        gpointer     user_data)      : Run Last