| Wocky Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Properties | Signals | ||||
#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);
GFlags +----WockyMucStatusCode
GEnum +----WockyMucRole
GEnum +----WockyMucAffiliation
GFlags +----WockyMucFeature
GEnum +----WockyMucMsgType
GEnum +----WockyMucMsgState
GEnum +----WockyMucState
GObject +----WockyMuc
"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
"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
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.
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.
| Unknown code | |
| Room entered is not anonymous | |
| Affiliation changed when not present | |
| Unavailable members visible | |
| Unavailable members invisible | |
| Non-privacy config change | |
| User's own presence | |
| Logging enabled | |
| Logging disabled | |
| Room is now non-anonymous | |
| Room is now semi-anonymous | |
| Room is now fully-anonymous | |
| Room created (eg by joining) | |
| Service enforced nick change | |
| User has been banned | |
| User's nick changed | |
| Kicked from the room | |
| Kicked (affiliation change) | |
| Kicked (room is now members-only) | |
| Kicked (shutdown) |
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.
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.
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.
| the MUC is modern, as documented in XEP-0045 | |
| the MUC has support for the mucregister FORM_TYPE | |
| the MUC has support for the mucregister FORM_TYPE | |
| the MUC has support for the mucregister FORM_TYPE | |
| the MUC is hidden | |
| only members can join this MUC | |
| the MUC is moderated | |
| the MUC is non-anonymous | |
| the MUC is open | |
| the MUC is password protected | |
| the MUC is persistent | |
| the MUC is public | |
| the MUC has a list of MUC rooms | |
| the MUC is semi-anonymous | |
| the MUC is temporary | |
| the MUC is unmoderated | |
| the MUC is unsecured | |
| the MUC has obsolete groupchat 1.0 features |
typedef enum {
WOCKY_MUC_MSG_NONE,
WOCKY_MUC_MSG_NORMAL,
WOCKY_MUC_MSG_ACTION,
WOCKY_MUC_MSG_NOTICE,
} WockyMucMsgType;
XMPP MUC message types.
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.
| no message state applies | |
| the contact in the MUC is active | |
| the contact in the MUC is composing a message | |
| the contact in the MUC is inactive | |
| the contact in the MUC has paused composing a message |
typedef enum {
WOCKY_MUC_CREATED = 0,
WOCKY_MUC_INITIATED,
WOCKY_MUC_AUTH,
WOCKY_MUC_JOINED,
WOCKY_MUC_ENDED,
} WockyMucState;
WockyMuc states.
| the WockyMuc has been created | |
| the MUC has been initiated on the server | |
| the user is authenticating with the MUC | |
| the user has joined the MUC and can chat | |
| the MUC has ended |
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 * |
the JID of the member (room@server/nick) |
gchar * |
the JID of the owner (owner@domain/resource) |
gchar * |
the nickname of the member |
WockyMucRole |
the WockyMucRole of the member |
WockyMucAffiliation |
the WockyMucAffiliation of the member |
gchar * |
the user set status string |
| the WockyStanza that was received regarding the member's presence |
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);
"affiliation" property"affiliation" WockyMucAffiliation : Read
The affiliation of the user with the MUC room.
Default value: WOCKY_MUC_AFFILIATION_NONE
"category" property"category" gchar* : Read
Category of the MUC, usually "conference".
Default value: NULL
"description" property"description" gchar* : Read
The long description oof the room.
Default value: NULL
"jid" property"jid" gchar* : Read / Write
Full room@service/nick JID of the MUC room.
Default value: NULL
"name" property"name" gchar* : Read
The human-readable name of the room (usually a short label).
Default value: NULL
"password" property"password" gchar* : Read / Write
User's MUC room password.
Default value: NULL
"porter" property "porter" WockyPorter* : Read / Write / Construct Only
The WockyPorter instance doing all the actual XMPP interaction.
"reserved-nick" property"reserved-nick" gchar* : Read
The user's reserved in-room nickname, if any.
Default value: NULL
"role" property"role" guint : Read
The role (WockyMucRole) of the user in the MUC room.
Allowed values: <= 3
Default value: 0
"service" property"service" gchar* : Read
The service (domain) part of the MUC JID.
Default value: NULL
"status-message" property"status-message" gchar* : Read
User's MUC status message.
Default value: NULL
"user" property"user" gchar* : Read / Write / Construct Only
Full JID of the user (node@domain/resource) who is connecting.
Default value: NULL
"error" signalvoid 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.
|
the MUC |
|
the presence stanza |
|
the type of error |
|
an error in domain WOCKY_XMPP_ERROR, whose message (if not NULL)
is a human-readable message from the server |
|
user data set when the signal handler was connected. |
"fill-presence" signalvoid user_function (WockyMuc *wockymuc,
WockyStanza *arg1,
gpointer user_data) : Run Last
"joined" signalvoid user_function (WockyMuc *muc,
WockyStanza *stanza,
guint codes,
gpointer user_data) : Run Last
Emitted when the local user successfully joins muc.
|
the MUC |
|
the presence stanza |
|
bitwise OR of WockyMucStatusCode flags with miscellaneous
information about the MUC |
|
user data set when the signal handler was connected. |
"left" signalvoid 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
|
the MUC |
|
the presence stanza |
|
bitwise OR of WockyMucStatusCode flags describing why member
left the MUC |
|
the (now ex-)member of the MUC who left |
|
if member was removed from the MUC by another participant, that
participant's JID |
|
if member was removed from the MUC by another participant, a
human-readable reason given by that participant |
|
a parting message provided by member, or NULL
|
|
user data set when the signal handler was connected. |
"message" signalvoid 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:
|
the MUC |
|
the incoming message stanza |
|
the message's type |
|
the stanza's identifier (which may be NULL if neither the sender nor
the MUC specified one) |
|
for messages received as scrollback when joining the MUC, the
time the message was sent; NULL for messages received while in the MUC |
|
a WockyMucMember struct describing the sender of the message |
|
the body of the message, or NULL
|
|
the new subject for the MUC, or NULL
|
|
whether sender is currently typing. |
|
user data set when the signal handler was connected. |
"message-error" signalvoid 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.
|
the MUC |
|
the incoming WOCKY_STANZA_SUB_TYPE_ERROR message |
|
the type of the message which was rejected |
|
the identifier for the original message and this error (which may be
NULL) |
|
the timestamp attached to the original message, which is
probably NULL because timestamps are only attached to scrollback messages |
|
a WockyMucMember struct describing the sender of the original
message (which is, we presume, us) |
|
the body of the message which failed to send |
|
the type of error |
|
an error in domain WOCKY_XMPP_ERROR, whose message (if not NULL)
is a human-readable message from the server |
|
user data set when the signal handler was connected. |
"nick-change" signalvoid user_function (WockyMuc *wockymuc,
WockyStanza *arg1,
guint arg2,
gpointer user_data) : Run Last
"own-presence" signalvoid user_function (WockyMuc *wockymuc,
WockyStanza *arg1,
guint arg2,
gpointer user_data) : Run Last
"parted" signalvoid 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.
|
the MUC |
|
the presence stanza |
|
bitwise OR of WockyMucStatusCode flags describing why the user
left the MUC |
|
if the user was removed from the MUC by another participant, that participant's JID |
|
if the user was removed from the MUC by another participant, a human-readable reason given by that participant |
|
a parting message we provided to other participants, or NULL
|
|
user data set when the signal handler was connected. |
"permissions" signalvoid 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.
|
the muc |
|
the presence stanza heralding the change |
|
bitwise OR of WockyMucStatusCode flags |
|
the JID of the user who changed our permissions, or NULL
|
|
a human-readable reason for the change, or NULL
|
|
user data set when the signal handler was connected. |