xmppOpen()
Opens a client communication channel to an XMPP server.
Synopsis
int xmppOpen(string jid, string password [, string|function_ptr callback [,
mapping options]]);
Parameter
| Parameter | Description |
|---|---|
| jid | Jabber ID such as winccoa.etm@jabber.at. |
| password | Jabber password. |
| callback | A callback function. |
| options |
The options mapping contains the following keys: host (string): host name of the XMPP server to which the connection is established (e.g. "jabber.org" or "talk.google.com"). It can also be an IP address in the form of a string (e.g. "192.168.1.25"). port(int): Port number at which the XMPP server is listening. The default value is 5222. The port is only used when also the host key is given. resource (string): When the jid did not contain a resource, this option defines it. autoAcceptSubscriptions (bool): Default = TRUE. if a client wants to receive presence information from the server, it sends a subscription request. If autoAcceptSubscriptions==true, the requests is automatically accepted. If you set this value to FALSE, the subscription request is not automatically accepted but must be accepted or refused via the functions xmppAcceptSubscription/xmppRefuseSubscription logging (string): Allows you to activate different debug flags to analyze the XMPP communication in detail. The following keywords are available:debug, info, warn, receive, send, any. These can be used in arbitrary order and by using an arbitrary delimiter.To see the debug messages, activate the debug flag -dbg XMPP for the manager that uses the XMPP functions. |
Return Value
Returns a unique id for this client channel (the clientId) or a number < 0 in case of errors
Errors
Errors can be queried via getLastError().
Description
Opens a client communication channel to an XMPP server, passing your jabber ID and your jabber password and returns a unique id for this client channel (the clientId) or a number < 0 in case of errors. You can query errors via getLastError().
The jid can be either a "bare jid" such as "winccoa.etm@jabber.at" or it can also contain a resource like "winccoa.etm@jabber.at/desktop". If no resource is given, the bare jid is used.
When you only want to send messages but not handle receiving messages, no callback function is required. If you need to handle incoming messages, a callback function must be implemented
void callback(mapping message);The callback function can be specified as a name (string) or as a function_ptr, e.g. a static public function of a class, like Receiver::callback. The message mapping argument in this callback can contain the following keys:
Parameters
| Parameter | Description |
|---|---|
| clientId (int) | The client channel from which the message is received. |
| type (string) | "subscriptionRequest" or "message" (see below). |
| messageType (string) | One of the options: error, normal, chat, groupchat, headline |
| * from (string) | The Jid of the sender. |
The following keys are only available in the type "message":
Parameters
| Parameter | Description |
|---|---|
| * to (string) | Receiver jid |
| * id (string) | Message id |
| * lang (string) | Language |
| body (string) | Message body text |
| * subject (string) | Message subject |
| * thread (string) | Message thread |
| * receiptId (string) | if this message is a delivery receipt, holds the id of the original message. |
| receiptRequested (bool) | Returns true if a delivery receipt is requested, as defined by XEP-0184: Message Delivery Receipts. |
| attentionRequested (bool) | Returns true if the user's attention is requested, as defined by XEP-0224: Attention. |
| * time (time) | Time stamp of delayed delivery, as defined by XEP-0203. |
The following example opens a connection to the jabber server with the user "winccoa.etm@jabber.at" and password and sends a message.
p =
xmppOpen("winccoa.etm@jabber.at","123677", "callback", m); DebugN("xmppOpen:",
p); by your own user and password. This code is an example!#uses "CtrlXmpp"
int p;
main(mapping event)
{
mapping m; /* options mapping for the xmppOpen function. */
int port;
string host;
string resource;
bool autoAcceptSubscriptions = TRUE;
string logging;
m["host"]= host;
m["port"] = port;
m["resource"] = resource;
m["autoAcceptSubscriptions"] = autoAcceptSubscriptions;
m["logging"] = "any";
/* Show all debug information (send, receive etc.).
You have to activate the debug flag for the manager that executed the XMPP functions
in order to show the debug info via the logging key.
See the parameters of this function in the beginning of this chapter */
/* Open a client communication channel to an XMPP server. */
p = xmppOpen("winccoa.etm@jabber.at","123677", "callback", m);
DebugN("xmppOpen:", p);
/* Options mapping for sending a message */
mapping mes;
bool attentionRequested = TRUE;
bool receiptRequested = TRUE;
string receiptId;
string thread;
string subject;
time t = getCurrentTime();
mes["attentionRequested"] = attentionRequested;
mes["receiptRequested"] = receiptRequested;
mes["receiptId"] = receiptId;
mes["thread"] = thread;
mes["subject"] = subject;
mes["time"] = t;
string rID;
/* Send the message with options attentionRequested = TRUE and receiptRequested = TRUE
as well as the current time.
The other parameters are not specified and thus the default values are used.*/
int j = xmppSendMessage(p,"winccoa.etm@jabber.at", "Hello this is a new message", mes, rID);
DebugN("Message sent:", j);
}
void callback(mapping message) /* Output the received message */
{
DebugN("Message:", message); //The message
dyn_string keys = mappingKeys(message);
for(int i = 1; i <= dynlen(keys); i++)
{
DebugTN("key: " + keys[i] + " | type: " +getTypeName(message[keys[i]]), "value:",mappingGetValue(message,i));
}
if (message.receiptRequested)
{
DebugN("Send confirmation to the server:", xmppSendMessage(message.clientId, message.from,"
", makeMapping("receiptId", message.id)));
DebugN("Message", message.clientId, "from:", message.from, "sent");
}
/* Close the connection */
int k;
DebugN("Close the connection:", k = xmppClose(p));
}Assignment
Availability
CTRL
