WockyMuc

WockyMuc — multi-user chat rooms

Functions

Properties

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

Signals

Types and Values

Object Hierarchy

    GEnum
    ├── WockyMucAffiliation
    ├── WockyMucMsgState
    ├── WockyMucMsgType
    ├── WockyMucRole
    ╰── WockyMucState
    GFlags
    ├── WockyMucFeature
    ╰── WockyMucStatusCode
    GObject
    ╰── WockyMuc

Includes

#include <wocky/wocky.h>

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.

Functions

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

Types and Values

enum WockyMucStatusCode

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

Members

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

WockyMuc roles as described in XEP-0045 §5.1.

Members

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

WockyMuc affiliations as described in XEP-0045 §5.2.

Members

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

WockyMuc feature flags.

Members

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

XMPP MUC message types.

Members

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

XMPP MUC message states as documeted in XEP-0085.

Members

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

WockyMuc states.

Members

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;

Members

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 WockyMucClass

struct WockyMucClass {
};

The class of a WockyMuc.

Property Details

The “affiliation” property

  “affiliation”              WockyMucAffiliation

The affiliation of the user with the MUC room.

Flags: Read

Default value: WOCKY_MUC_AFFILIATION_NONE


The “category” property

  “category”                 gchar *

Category of the MUC, usually "conference".

Flags: Read

Default value: NULL


The “description” property

  “description”              gchar *

The long description oof the room.

Flags: Read

Default value: NULL


The “jid” property

  “jid”                      gchar *

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

Flags: Read / Write

Default value: NULL


The “muc-flags” property

  “muc-flags”                gulong

ORed set of WockyMucFeature MUC property flags.

Flags: Read


The “name” property

  “name”                     gchar *

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

Flags: Read

Default value: NULL


The “nickname” property

  “nickname”                 gchar *

The user's in-room nickname.

Flags: Read

Default value: NULL


The “password” property

  “password”                 gchar *

User's MUC room password.

Flags: Read / Write

Default value: NULL


The “porter” property

  “porter”                   WockyPorter *

The WockyPorter instance doing all the actual XMPP interaction.

Flags: Read / Write / Construct Only


The “reserved-nick” property

  “reserved-nick”            gchar *

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

Flags: Read

Default value: NULL


The “role” property

  “role”                     guint

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

Flags: Read

Allowed values: <= 3

Default value: 0


The “room” property

  “room”                     gchar *

The node part of the MUC room JID.

Flags: Read

Default value: NULL


The “service” property

  “service”                  gchar *

The service (domain) part of the MUC JID.

Flags: Read

Default value: NULL


The “status-message” property

  “status-message”           gchar *

User's MUC status message.

Flags: Read

Default value: NULL


The “type” property

  “type”                     gchar *

Type of the MUC, eg "text".

Flags: Read

Default value: NULL


The “user” property

  “user”                     gchar *

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

Flags: Read / Write / Construct Only

Default value: NULL

Signal Details

The “error” signal

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

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

Parameters

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.

 

Flags: Run Last


The “fill-presence” signal

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

Flags: Run Last


The “joined” signal

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

Emitted when the local user successfully joins muc .

Parameters

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.

 

Flags: Run Last


The “left” signal

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

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

Parameters

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.

 

Flags: Run Last


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)

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.

Parameters

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.

 

Flags: Run Last


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)

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

Parameters

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.

 

Flags: Run Last


The “nick-change” signal

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

Flags: Run Last


The “own-presence” signal

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

Flags: Run Last


The “parted” signal

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

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

Parameters

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.

 

Flags: Run Last


The “permissions” signal

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

Emitted when our permissions within the MUC are changed.

Parameters

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.

 

Flags: Run Last


The “presence” signal

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

Flags: Run Last