Module exmpp_stream

The module exmpp_stream provides utilities to open and close an XMPP stream, negotiate features and handle stream errors.

Authors: Jean-Sébastien Pédron (js.pedron@meetic-corp.com).

Description

The module exmpp_stream provides utilities to open and close an XMPP stream, negotiate features and handle stream errors.

exmpp_client_stream and exmpp_server_stream should be prefered to exmpp_stream because they'll set some defaults values for the caller.

Stream handling

It covers these basic functions:

A common use case is illustrated in table 1.

Table 1: stream opening and closing
Client-side Server-side

The client call exmpp_stream:

Opening = exmpp_stream:opening(
    "jabber.example.com",
    ?NS_JABBER_CLIENT,
    "1.0"
).

After serialization, this produces this XML message:

<stream:stream xmlns:stream="http://etherx.jabber.org/streams"
    xmlns="jabber:client" to="jabber.example.org" version="1.0">

If the server accepts the client stream opening, it'll call:

Opening_Reply = exmpp_stream:opening_reply(
    Opening,
    random
).

After serialization, this produces this XML message:

<stream:stream xmlns:stream="http://etherx.jabber.org/streams"
    xmlns="jabber:client" version="1.0" from="jabber.example.org"
    id="stream-396429316">

Note that exmpp_stream generated an ID automatically; you may override this.

At the end of the communication, the client close its stream:

Client_Closing = exmpp_stream:closing().

After serialization, this produces this XML message:

</stream:stream>

The server do the same:

Server_Closing = exmpp_stream:closing(Client_Closing).

After serialization, this produces this XML message:

</stream:stream>

The server may use the same function clause than the client but here, it gives the client closing to the function. This is to be sure to use the same XML prefix.

Function Index

closing/0Make a </stream> closing tag.
closing/1Make a </stream> closing tag for the given Opening tag.
error/1Make a standard <stream:error> element based on the given Condition.
error/2
features/1Make the features annoucement element.
get_condition/1Return the child element name corresponding to the stanza error condition.
get_default_ns/1Return the default namespace.
get_id/1Return the stream ID.
get_initiating_entity/1Return the initiating entity hostname.
get_lang/1Return the language of the stream.
get_receiving_entity/1Return the receiving entity hostname.
get_text/1Return the text that describes the error.
get_version/1Return the version of the stream.
is_error/1Tell if this element is a stream error.
opening/3Make a <stream> opening tag.
opening/4Make a <stream> opening tag.
opening_reply/2Make a <stream> opening reply tag for the given Opening tag.
opening_reply/3Make a <stream> opening reply tag for the given Opening tag.
opening_reply/4Make a <stream> opening reply tag.
opening_reply/5Make a <stream> opening reply tag.
parse_version/1Parse the stream version in String.
serialize_version/1Make a binary() for the version attribute of a stream element.
set_default_ns/2Set the default namespace.
set_dialback_support/1Declare server diablack support.
set_id/2Set the stream ID.
set_initiating_entity/2Set the initiating entity in the from attribute.
set_lang/2Set the default language.
set_receiving_entity/2Set the receiving entity in the to attribute.
set_version/2Set the protocol version.
to_binary/1Serialize a stream opening/closing.
to_iolist/1Serialize a stream opening/closing.
to_list/1Serialize a stream opening/closing.

Function Details

closing/0

closing() -> Closing

Make a </stream> closing tag.

closing/1

closing(Xmlel::Opening) -> Closing

Make a </stream> closing tag for the given Opening tag.

error/1

error(Condition) -> Stream_Error

Make a standard <stream:error> element based on the given Condition.

error/2

error(Condition, X2) -> any()

features/1

features(Features) -> Features_Announcement

Make the features annoucement element.

get_condition/1

get_condition(Xmlel::Stream_Error) -> Condition | undefined

Return the child element name corresponding to the stanza error condition.

get_default_ns/1

get_default_ns(Xmlel::Opening) -> Default_NS | undefined

Return the default namespace.

XMPP-IM defines jabber:client and jabber:server.

get_id/1

get_id(Opening) -> ID | undefined

Return the stream ID.

get_initiating_entity/1

get_initiating_entity(Opening) -> Hostname | undefined

Return the initiating entity hostname.

get_lang/1

get_lang(Opening) -> Lang | undefined

Return the language of the stream.

get_receiving_entity/1

get_receiving_entity(Opening) -> Hostname | undefined

Return the receiving entity hostname.

get_text/1

get_text(Xmlel::Stream_Error) -> Text | undefined

Return the text that describes the error.

get_version/1

get_version(Opening) -> Version

Return the version of the stream.

is_error/1

is_error(Xmlel::XML_El) -> bool()

Tell if this element is a stream error.

opening/3

opening(To, Default_NS, Version) -> Opening

Make a <stream> opening tag.

See also: opening/4.

opening/4

opening(To, Default_NS, Version, Lang) -> Opening

Make a <stream> opening tag.

This element is supposed to be sent by the initiating entity to the receiving entity (for the other way around, see opening_reply/1).

opening_reply/2

opening_reply(Xmlel::Opening, ID) -> Opening_Reply

Make a <stream> opening reply tag for the given Opening tag.

This element is supposed to be sent by the receiving entity in reply to the initiating entity (for the other way around, see opening/1).

If ID is random, one will be generated automatically.

opening_reply/3

opening_reply(Xmlel::Opening, ID, Lang) -> Opening_Reply

Make a <stream> opening reply tag for the given Opening tag.

This element is supposed to be sent by the receiving entity in reply to the initiating entity (for the other way around, see opening/1).

If ID is random, one will be generated automatically.

opening_reply/4

opening_reply(From, Default_NS, Version, ID) -> Opening_Reply

Make a <stream> opening reply tag.

See also: opening_reply/5.

opening_reply/5

opening_reply(From, Default_NS, Version, ID, Lang) -> Opening_Reply

Make a <stream> opening reply tag.

This element is supposed to be sent by the receiving entity in reply to the initiating entity (for the other way around, see opening/1).

If ID is random, one will be generated automatically.

parse_version/1

parse_version(String) -> Version

Parse the stream version in String.

serialize_version/1

serialize_version(X1::Version) -> Binary

Make a binary() for the version attribute of a stream element.

set_default_ns/2

set_default_ns(Xmlel::Opening, NS) -> New_Opening

Set the default namespace.

XMPP-IM defines jabber:client and jabber:server.

set_dialback_support/1

set_dialback_support(Opening) -> New_Opening

Declare server diablack support.

set_id/2

set_id(Xmlel::Opening, ID) -> New_Opening

Set the stream ID.

set_initiating_entity/2

set_initiating_entity(Xmlel::Opening, Hostname) -> New_Opening

Set the initiating entity in the from attribute.

set_lang/2

set_lang(Xmlel::Opening, Lang) -> New_Opening

Set the default language.

set_receiving_entity/2

set_receiving_entity(Xmlel::Opening, Hostname) -> New_Opening

Set the receiving entity in the to attribute.

set_version/2

set_version(Xmlel::Opening, Version) -> New_Opening

Set the protocol version.

to_binary/1

to_binary(El) -> XML_Text

Serialize a stream opening/closing.

to_iolist/1

to_iolist(El) -> XML_Text

Serialize a stream opening/closing.

to_list/1

to_list(El) -> XML_Text

Serialize a stream opening/closing.


Generated by EDoc, Jan 21 2011, 01:43:51.