Sluift

This document describes the API of the sluift module.

The entry points of Sluift are in the sluift module, described below.

sluift module

This module provides methods for XMPP communication.

The main entry point of this module is the new_client method, which creates a new client for communicating with an XMPP server.

Fields

• base64
• disco
• idn
• jid

Methods

• copy: Perform a shallow copy of object.
• from_xml: Convert a raw XML string into a structured representation.
• get_help: Retrieves the help information from target.
• help: Prints the help of target.
• hexify: Convert binary data into hexadecimal format.
• new_client: Creates a new client.
• new_uuid: Generates a new UUID
• sha1: Compute the SHA–1 hash of given data
• sleep: Sleeps for the given time.
• to_xml: Convert a structured element into XML.
• tprint: Pretty-print a table
• unhexify: Convert hexadecimal data into binary data.

copy

Perform a shallow copy of object.

Parameters

• object: the object to copy

from_xml

Convert a raw XML string into a structured representation.

Parameters

• string: the string to convert

get_help

Retrieves the help information from target.

Returns a table with the following fields:

• description: the description of target
• parameters: an array of parameters of target represented as tables with name and description fields.
• options: an array of options (named parameters) of target represented as tables with name and description fields.
• methods: an array of methods
• fields: an array of fields

Parameters

• target: The target to retrieve help of

help

Prints the help of target.

target can be any object. When target is a string, prints the help of the class with the given name.

Parameters

• target: The target to retrieve help of

hexify

Convert binary data into hexadecimal format.

Parameters

• data: the data to convert

new_client

Creates a new client.

Returns a Client object.

Parameters

• jid: The JID to connect as
• passphrase: The passphrase to use

new_uuid

Generates a new UUID

sha1

Compute the SHA–1 hash of given data

Parameters

• data: the data to hash

sleep

Sleeps for the given time.

Parameters

• milliseconds: the amount of milliseconds to sleep

to_xml

Convert a structured element into XML.

Parameters

• element: the element to convert

tprint

Pretty-print a table

Parameters

• table: the table to print

unhexify

Convert hexadecimal data into binary data.

Parameters

• data: the data in hexadecimal format

Client class

Client interface

Methods

• add_contact: Add a contact to the contact list.
• async_connect: Connect to the server asynchronously.
• cancel_subscription: Cancel the subscription of a contact.
• confirm_subscription: Confirm subscription of a contact.
• connect: Connect to the server.
• disconnect: Disconnect from the server
• events: Returns an iterator over all events.
• for_each_event: Calls f for each event.
• for_each_message: Call f for all events of type message.
• for_each_presence: Call f for all events of type presence.
• for_each_pubsub_event: Call f for all events of type pubsub.
• get: Sends a get query.
• get_contacts: Returns a table of all the contacts in the contact list.
• get_disco_items: Sends a get query of type disco_items.
• get_dom: Sends a get query of type dom.
• get_next_event: Returns the next event.
• get_next_message: Get the next event of type message.
• get_next_presence: Get the next event of type presence.
• get_next_pubsub_event: Get the next event of type pubsub.
• get_software_version: Sends a get query of type software_version.
• get_vcard: Sends a get query of type vcard.
• get_xml: Sends a get query of type xml.
• is_connected: Checks whether this client is still connected.
• jid: Returns the JID of this client
• messages: Returns an iterator over all events of type message.
• process_events: Process all pending events
• pubsub: Returns a PubSub object for communicating with the PubSub service at jid.
• pubsub_events: Returns an iterator over all events of type pubsub.
• query_pubsub
• remove_contact: Remove a contact from the contact list.
• send: Sends a raw string
• send_message: Send a message.
• send_presence: Send presence.
• set: Sends a set query.
• set_caps_node: Sets the caps node of this client
• set_command: Sends a set query of type command.
• set_disco_info: Sets the service discovery information for this client
• set_options: Sets the connection options of this client.
• set_version: Sets the published version of this client.
• wait_connected: Block until the client is connected.

add_contact

Add a contact to the contact list.

Parameters

• self

Options

• jid: The JID of the contact to add
• name: The name to use in the contact list
• groups: An array of group names to add the contact to

async_connect

Connect to the server asynchronously.

This method immediately returns.

Parameters

• self

Options

• host: The host to connect to. When omitted, is determined by resolving the client JID.
• port: The port to connect to. When omitted, is determined by resolving the client JID.

cancel_subscription

Cancel the subscription of a contact.

Parameters

• self
• jid: the JID of the contact to cancel the subscription of

confirm_subscription

Confirm subscription of a contact.

Parameters

• self
• jid: the JID of the contact to confirm the subscription of

connect

Connect to the server.

This method blocks until the connection has been established.

Parameters

• self

Options

• host: The host to connect to. When omitted, is determined by resolving the client JID.
• port: The port to connect to. When omitted, is determined by resolving the client JID.

disconnect

Disconnect from the server

Parameters

• self

events

Returns an iterator over all events.

This function blocks until timeout is reached (or blocks forever if it is omitted).

Parameters

• self

Options

• type: The type of event to return (message, presence, pubsub). When omitted, all event types are returned.
• timeout: The amount of time to wait for events.
• if: A function to filter events. When this function, called with the event as a parameter, returns true, the event will be returned

for_each_event

Calls f for each event.

Parameters

• self

Options

• type: The type of event to return (message, presence, pubsub). When omitted, all event types are returned.
• timeout: The amount of time to wait for events.
• if: A function to filter events. When this function, called with the event as a parameter, returns true, the event will be returned
• f: The functor to call with each event. Required.

for_each_message

Call f for all events of type message.

Parameters

• self

Options

• timeout: The amount of time to wait for events.
• if: A function to filter events. When this function, called with the event as a parameter, returns true, the event will be returned
• f: The functor to call with each event. Required.

for_each_presence

Call f for all events of type presence.

Parameters

• self

Options

• timeout: The amount of time to wait for events.
• if: A function to filter events. When this function, called with the event as a parameter, returns true, the event will be returned
• f: The functor to call with each event. Required.

for_each_pubsub_event

Call f for all events of type pubsub.

Parameters

• self

Options

• timeout: The amount of time to wait for events.
• if: A function to filter events. When this function, called with the event as a parameter, returns true, the event will be returned
• f: The functor to call with each event. Required.

get

Sends a get query.

Parameters

• self

Options

• timeout: The amount of time to wait for the query to finish
• to: The JID of the target to send the query to
• query: The query to send

get_contacts

Returns a table of all the contacts in the contact list.

Parameters

• self

get_disco_items

Sends a get query of type disco_items. Apart from the options below, all top level elements of disco_items can be passed.

Parameters

• self

Options

• timeout: The amount of time to wait for the query to finish
• to: The JID of the target to send the query to
• query: The query to send

get_dom

Sends a get query of type dom. Apart from the options below, all top level elements of dom can be passed.

Parameters

• self

Options

• timeout: The amount of time to wait for the query to finish
• to: The JID of the target to send the query to
• query: The query to send

get_next_event

Returns the next event.

Parameters

• self

Options

• type: The type of event to return (message, presence, pubsub). When omitted, all event types are returned.
• timeout: The amount of time to wait for events.
• if: A function to filter events. When this function, called with the event as a parameter, returns true, the event will be returned

get_next_message

Get the next event of type message.

Parameters

• self

Options

• type: The type of event to return (message, presence, pubsub). When omitted, all event types are returned.
• timeout: The amount of time to wait for events.
• if: A function to filter events. When this function, called with the event as a parameter, returns true, the event will be returned

get_next_presence

Get the next event of type presence.

Parameters

• self

Options

• type: The type of event to return (message, presence, pubsub). When omitted, all event types are returned.
• timeout: The amount of time to wait for events.
• if: A function to filter events. When this function, called with the event as a parameter, returns true, the event will be returned

get_next_pubsub_event

Get the next event of type pubsub.

Parameters

• self

Options

• type: The type of event to return (message, presence, pubsub). When omitted, all event types are returned.
• timeout: The amount of time to wait for events.
• if: A function to filter events. When this function, called with the event as a parameter, returns true, the event will be returned

get_software_version

Sends a get query of type software_version. Apart from the options below, all top level elements of software_version can be passed.

Parameters

• self

Options

• timeout: The amount of time to wait for the query to finish
• to: The JID of the target to send the query to
• query: The query to send

get_vcard

Sends a get query of type vcard. Apart from the options below, all top level elements of vcard can be passed.

Parameters

• self

Options

• timeout: The amount of time to wait for the query to finish
• to: The JID of the target to send the query to
• query: The query to send

get_xml

Sends a get query of type xml. Apart from the options below, all top level elements of xml can be passed.

Parameters

• self

Options

• timeout: The amount of time to wait for the query to finish
• to: The JID of the target to send the query to
• query: The query to send

is_connected

Checks whether this client is still connected.

Returns a boolean.

Parameters

• self

jid

Returns the JID of this client

Parameters

• self

messages

Returns an iterator over all events of type message.

Parameters

• self

Options

• timeout: The amount of time to wait for events.
• if: A function to filter events. When this function, called with the event as a parameter, returns true, the event will be returned
• f: The functor to call with each event. Required.

process_events

Process all pending events

Parameters

• self

pubsub

Returns a PubSub object for communicating with the PubSub service at jid.

Parameters

• self
• jid: The JID of the PubSub service

pubsub_events

Returns an iterator over all events of type pubsub.

Parameters

• self

Options

• timeout: The amount of time to wait for events.
• if: A function to filter events. When this function, called with the event as a parameter, returns true, the event will be returned
• f: The functor to call with each event. Required.

query_pubsub

remove_contact

Remove a contact from the contact list.

Parameters

• self
• jid: the JID of the contact to remove

send

Sends a raw string

Parameters

• self
• data: the string to send

send_message

Send a message.

Parameters

• self
• body: the body of the message. Can alternatively be specified using the body option

Options

• type: the type of message to send (normal, chat, error, groupchat, headline)
• to: the JID to send the message to
• body: the body of the message

send_presence

Send presence.

Parameters

• self
• body: the text of the presence. Can alternatively be specified using the status option

Options

• status: the text of the presence
• priority: the priority of the presence
• to: the JID to send the message to
• type: the type of message to send (available, error, probe, subscribe, subscribed, unavailable, unsubscribe, unsubscribed)

set

Sends a set query.

Parameters

• self

Options

• timeout: The amount of time to wait for the query to finish.
• to: The JID of the target to send the query to
• query: The query to send.

set_caps_node

Sets the caps node of this client

Parameters

• self
• node: The caps node (e.g. ‘http://swift.im/sluift’)

set_command

Sends a set query of type command. Apart from the options below, all top level elements of command can be passed.

Parameters

• self

Options

• timeout: The amount of time to wait for the query to finish
• to: The JID of the target to send the query to
• query: The query to send

set_disco_info

Sets the service discovery information for this client

Parameters

• self
• disco_info: A structured representation of the service discovery information

set_options

Sets the connection options of this client.

Parameters

• self

Options

• host: The host to connect to. When omitted, is determined from resolving the JID domain.
• port: The port to connect to. When omitted, is determined from resolving the JID domain.
• allow_plain_without_tls: Allow PLAIN authentication without a TLS encrypted connection
• compress: Use stream compression when available
• ack: Request acknowledgements
• bosh_url: Connect using the specified BOSH URL
• tls: Use TLS when available

set_version

Sets the published version of this client.

Parameters

• self

Options

• os: the OS this client is running on
• version: the version identifier of this client
• name: the name of the client software

wait_connected

Block until the client is connected.

This is useful after an async_connect.

Parameters

• self

PubSub class

Interface to communicate with a PubSub service

Methods

• events
• for_each_event
• get_affiliations
• get_default_configuration
• get_default_subscription_options
• get_next_event
• get_subscriptions
• list_nodes
• node

events

for_each_event

get_affiliations

get_default_configuration

get_default_subscription_options

get_next_event

get_subscriptions

list_nodes

node

PubSubNode class

Interface to communicate with a PubSub node on a service

Methods

• create
• delete
• events
• for_each_event
• get_affiliations
• get_configuration
• get_default_subscription_options
• get_item
• get_items
• get_next_event
• get_owner_affiliations
• get_owner_subscriptions
• get_subscription_options
• get_subscriptions
• list_items
• publish
• purge
• retract
• set_configuration
• set_owner_affiliations
• subscribe
• unsubscribe

create

delete

events

for_each_event

get_affiliations

get_configuration

get_default_subscription_options

get_item

get_items

get_next_event

get_owner_affiliations

get_owner_subscriptions

get_subscription_options

get_subscriptions

list_items

publish

purge

retract

set_configuration

set_owner_affiliations

subscribe

unsubscribe

PubSubRetract class

This table has the following fields:

• node: string
• items: array<PubSubItem>
• notify: boolean

PubSubAffiliations class

This table has the following fields:

• node: string (Optional)
• affiliations: array<PubSubAffiliation>

PubSubPublish class

This table has the following fields:

• node: string
• items: array<PubSubItem>

PubSubItems class

This table has the following fields:

• node: string
• items: array<PubSubItem>
• maximum_items: number (Optional)
• subscriptionid: string (Optional)

PubSubOwnerRedirect class

This table has the following fields:

• uri: string

PubSubEventRedirect class

This table has the following fields:

• uri: string

PubSubConfigure class

This table has the following fields:

• data: Form

PubSubEventDisassociate class

This table has the following fields:

• node: string

PubSubOwnerAffiliations class

This table has the following fields:

• node: string
• affiliations: array<PubSubOwnerAffiliation>

PubSubOwnerConfigure class

This table has the following fields:

• node: string (Optional)
• data: Form

UserLocation class

This table has the following fields:

• area: string (Optional)
• altitude: float (Optional)
• locality: string (Optional)
• latitude: float (Optional)
• accuracy: float (Optional)
• description: string (Optional)
• country_code: string (Optional)
• timestamp: datetime (string) (Optional)
• floor: string (Optional)
• building: string (Optional)
• room: string (Optional)
• country: string (Optional)
• region: string (Optional)
• uri: string (Optional)
• longitude: float (Optional)
• error: float (Optional)
• postal_code: string (Optional)
• bearing: float (Optional)
• text: string (Optional)
• datum: string (Optional)
• street: string (Optional)
• speed: float (Optional)

PubSubSubscribeOptions class

This table has the following fields:

• required: boolean

PubSubOwnerSubscriptions class

This table has the following fields:

• node: string
• subscriptions: array<PubSubOwnerSubscription>

PubSubDefault class

This table has the following fields:

• node: string (Optional)
• type: "none", "collection", or "leaf"

PubSubEventCollection class

This table has the following fields:

• node: string (Optional)
• disassociate: PubSubEventDisassociate
• associate: PubSubEventAssociate

PubSubEventSubscription class

This table has the following fields:

• node: string
• jid: jid (string)
• subscription: "none", "pending", "subscribed", or "unconfigured"
• subscriptionid: string (Optional)
• expiry: datetime (string)

PubSubEventRetract class

This table has the following fields:

• id: string

PubSubItem class

This table has the following fields:

• data: array<element (table)>
• id: string

PubSubUnsubscribe class

This table has the following fields:

• node: string (Optional)
• jid: jid (string)
• subscriptionid: string (Optional)

PubSubEventDelete class

This table has the following fields:

• node: string
• redirects: PubSubEventRedirect

PubSubCreate class

This table has the following fields:

• node: string
• configure: PubSubConfigure

PubSubOwnerPurge class

This table has the following fields:

• node: string

PubSubEventItems class

This table has the following fields:

• node: string
• items: array<PubSubEventItem>
• retracts: array<PubSubEventRetract>

PubSubOptions class

This table has the following fields:

• node: string
• jid: jid (string)
• data: Form
• subscriptionid: string (Optional)

PubSubEventItem class

This table has the following fields:

• node: string (Optional)
• publisher: string (Optional)
• data: array<element (table)>
• id: string (Optional)

PubSubOwnerSubscription class

This table has the following fields:

• jid: jid (string)
• subscription: "none", "pending", "subscribed", or "unconfigured"

PubSubOwnerAffiliation class

This table has the following fields:

• jid: jid (string)
• type: "none", "member", "outcast", "owner", "publisher", or "publish_only"

PubSubEventPurge class

This table has the following fields:

• node: string

PubSubAffiliation class

This table has the following fields:

• node: string
• type: "none", "member", "outcast", "owner", "publisher", or "publish_only"

PubSubSubscribe class

This table has the following fields:

• node: string (Optional)
• jid: jid (string)
• options: PubSubOptions

PubSubOwnerDelete class

This table has the following fields:

• node: string
• redirect: PubSubOwnerRedirect

PubSubOwnerDefault class

This table has the following fields:

• data: Form

PubSubSubscriptions class

This table has the following fields:

• node: string (Optional)
• subscriptions: array<PubSubSubscription>

PubSubEventAssociate class

This table has the following fields:

• node: string

PubSubSubscription class

This table has the following fields:

• node: string (Optional)
• subscriptionid: string (Optional)
• jid: jid (string)
• options: PubSubSubscribeOptions
• subscription: "none", "pending", "subscribed", or "unconfigured"

PubSubEventConfiguration class

This table has the following fields:

• node: string
• data: Form

DiscoInfo class

Represents disco#info service discovery data.

This table has the following structure:

• node: string
• identities: array(table)
• name: string
• category: string
• type: string
• language: string
• features: array(string)