{"id":15019064,"url":"https://github.com/processone/xmpp","last_synced_at":"2025-05-15T07:03:30.431Z","repository":{"id":37514270,"uuid":"74045359","full_name":"processone/xmpp","owner":"processone","description":"Erlang/Elixir XMPP parsing and serialization library on top of Fast XML","archived":false,"fork":false,"pushed_at":"2025-05-07T11:14:01.000Z","size":2916,"stargazers_count":141,"open_issues_count":14,"forks_count":89,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-05-07T12:27:04.982Z","etag":null,"topics":["erlang","serialization-library","xmpp"],"latest_commit_sha":null,"homepage":"http://process-one.net","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/processone.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-11-17T16:24:26.000Z","updated_at":"2025-05-07T11:14:05.000Z","dependencies_parsed_at":"2023-11-22T18:33:37.300Z","dependency_job_id":"7605fbc9-5595-4da0-a0bf-7b00a1cedc2c","html_url":"https://github.com/processone/xmpp","commit_stats":{"total_commits":550,"total_committers":18,"mean_commits":"30.555555555555557","dds":0.6599999999999999,"last_synced_commit":"c44dcaeda30b7b0d5e13b0d08e2421767281b53d"},"previous_names":[],"tags_count":74,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/processone%2Fxmpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/processone%2Fxmpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/processone%2Fxmpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/processone%2Fxmpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/processone","download_url":"https://codeload.github.com/processone/xmpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254291961,"owners_count":22046424,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["erlang","serialization-library","xmpp"],"created_at":"2024-09-24T19:52:55.843Z","updated_at":"2025-05-15T07:03:30.238Z","avatar_url":"https://github.com/processone.png","language":"Erlang","readme":"Erlang/Elixir XMPP library\n==========================\n\n[![CI](https://github.com/processone/xmpp/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/processone/xmpp/actions/workflows/ci.yml)\n[![Coverage Status](https://coveralls.io/repos/processone/xmpp/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/processone/xmpp?branch=master)\n[![Hex version](https://img.shields.io/hexpm/v/xmpp.svg \"Hex version\")](https://hex.pm/packages/xmpp)\n\nThe library provides comprehensive representation\nof XMPP elements as well as tools to work with them. Every such element\nis represented by an Erlang record. Most of the library's code is auto generated\nand thus considered to be bug free and efficient.\n\nThe approach is very similar to [ASN.1](https://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One),\n[Google Protocol Buffers](https://en.wikipedia.org/wiki/Protocol_Buffers) or\n[Apache Thrift](https://en.wikipedia.org/wiki/Apache_Thrift): an XML element\nis transformed into internal language structure (an Erlang record in our case) - the process\nknown as \"decoding\". During decoding, validation is also performed, thus well-typed\nstructures are generated, potentially decreasing bugs related to handcrafted parsing.\nA reverse process known as \"encoding\" is applied for transforming an Erlang record\ninto an XML element.\n\nThe library should be used along with [fast_xml](https://github.com/processone/fast_xml)\nlibrary, because it is only able to decode from and encode to structures\ngenerated by that library (that is, `xmlel()` elements).\n\n**Table of Contents**:\n1. [Status](#status)\n2. [Compiling](#compiling)\n3. [API](#api)\n4. [Usage](#usage)\n   1. [Initialization and header files](#initialization-and-header-files)\n   2. [XMPP elements](#xmpp-elements)\n   3. [Decoding and encoding](#decoding-and-encoding)\n   4. [Stanzas](#stanzas)\n      1. [Common fields](#common-fields)\n      2. [Constructing stanza responses](#constructing-stanza-responses)\n   5. [Error elements](#error-elements)\n   6. [Text elements](#text-elements)\n   7. [Pretty printer](#pretty-printer)\n   8. [Namespaces](#namespaces)\n   9. [XMPP addresses](#xmpp-addresses)\n   10. [Language translation](#language-translation)\n5. [Supported XMPP elements](#supported-xmpp-elements)\n\n# Status\n\nThe library is considered as production ready and has been used in\n[ejabberd XMPP server](https://www.process-one.net/en/ejabberd) since version 16.12.\nHowever, the API is quite unstable so far and incompatibilities may be introduced\nfrom release to release. The stable API will be denoted by `2.x` tag in the future.\n\n# Dependency\n\nYou need at least Erlang OTP 19.0.\n\n# Compiling\n\nAs usual, the following commands are used to obtain and compile the library:\n```\n$ git clone https://github.com/processone/xmpp.git\n$ cd xmpp\n$ make\n```\n\n# API\n\nThe full API is documented in [doc/API.md](doc/API.md)\n\n# Usage\n\n## Initialization and header files\n\nBefore calling any function from the library, `xmpp` application should be\nstarted.\n\nAlthough there are several header files which a developer might find useful\nto look into, they should **not** be included directly in the code. Only\n[include/xmpp.hrl](include/xmpp.hrl) file should be included, because\nit already includes all needed headers and also defines some useful macros.\nSo the typical code should look like:\n```erlang\n%% file: foo.erl\n-module(foo).\n-include_lib(\"xmpp/include/xmpp.hrl\").\n...\nstart() -\u003e\n    application:start(xmpp),\n    ...\n```\n\n## XMPP elements\n\nAll XMPP elements (records) are defined in [include/xmpp_codec.hrl](include/xmpp_codec.hrl)\nfile. For convenience, every record has the corresponding type spec.\nThere is also predefined `xmpp_element()` type which is a container for all\ndefined record types: so sometimes we will refer to an arbitrary XMPP element as\n`xmpp_element()` in the rest of this document. These records are generated\nautomatically by\n[XML generator](https://github.com/processone/fast_xml/blob/master/src/fxml_gen.erl)\nfrom specification file\n[specs/xmpp_codec.spec](specs/xmpp_codec.spec).\nThe specification file contains information about XML elements\ndefined within XMPP related namespace.\n\n\u003e **TODO**: writing specs for new elements will be documented later. For now\n\u003e you can learn by example: pick up a spec of any element which is very close\n\u003e to the one you want to add a spec for and use it as a pattern\n\n\u003e **WARNING**: you should **not** include `xmpp_codec.hrl` in your erlang code.\n\u003e Include `xmpp.hrl` instead. `xmpp_codec.hrl` should be only used to\n\u003e consult definitions of existing XMPP elements.\n\n## Decoding and encoding\n\nOnce an `xmlel()` element is obtained (either using `fxml_stream:parse_element/1`\nfunction or by any other means), it can be decoded using either [decode/1](doc/API.md#decode1)\nor [decode/3](doc/API.md#decode3) functions. The result will be an XMPP element. Note\nthat decoding might fail if there is no known XMPP element for the provided\n`xmlel()` element, or `xmlel()` is invalid, so you should call these functions\ninside `try ... catch`. Exceptions returned during decoding can be formatted using\n[format_error/1](doc/API.md#format_error1) or [io_format_error/1](doc/API.md#io_format_error1)\nfunctions.\n\n**Example**:\n```erlang\nhandle(#iq{type = get, sub_els = [El]} = IQ) -\u003e\n    try xmpp:decode(El) of\n        Pkt -\u003e handle_iq_child_element(Pkt)\n    catch _:{xmpp_codec, Reason} -\u003e\n        Txt = xmpp:format_error(Reason),\n\tio:format(\"iq has malformed child element: ~s\", [Txt]),\n\thandle_iq_with_malformed_child_element(IQ)\n    end.\n```\n\n[encode/1](doc/API.md#encode1) and [encode/2](doc/API.md#encode2) functions can be used for reverse\ntransformation, i.e. to encode an XMPP element into `xmlel()` element.\nEncoding would never fail as long as provided XMPP element is valid.\n\n## Stanzas\n\nAmongst all XMPP elements defined in the library, the most notable ones\nare stanzas: `message()`, `presence()` and `iq()` elements. A large part of `xmpp`\nmodule deals with stanzas.\n\n### Common fields\n\nRecords of all stanzas have several common fields:\n`id`, `type`, `lang`, `from`, `to`, `sub_els` and `meta`. Although it's\nacceptable to manipulate with these fields directly (which is useful in\npattern matching, for example), `xmpp` module provides several functions\nto work with them:\n- `id`: [get_id/1](doc/API.md#get_id1) and [set_id/2](doc/API.md#set_id2) can be used\n- `type`: [get_type/1](doc/API.md#get_type1) and [set_type/2](doc/API.md#set_type2) can be used\n- `lang`: [get_lang/1](doc/API.md#get_lang1) and [set_lang/2](doc/API.md#set_lang2) can be used\n- `from` and `to`: [get_from/1](doc/API.md#get_from1), [get_to/1](doc/API.md#get_to1),\n  [set_from/2](doc/API.md#set_from2), [set_to/2](doc/API.md#set_to2) and [set_from_to/3](doc/API.md#set_from_to3)\n  can be used\n- `sub_els`: [get_els/1](doc/API.md#get_els1) and [set_els/2](doc/API.md#set_els2) can be used;\n  additional functions to work with subtags directly are:\n  [set_subtag/2](doc/API.md#set_subtag2), [get_subtag/2](doc/API.md#get_subtag2),\n  [get_subtags/2](doc/API.md#get_subtags2), [try_subtag/2](doc/API.md#try_subtag2),\n  [try_subtags/2](doc/API.md#try_subtags2), [remove_subtag/2](doc/API.md#remove_subtag2),\n  [has_subtag/2](doc/API.md#has_subtag2), and [append_subtags/2](doc/API.md#append_subtags2).\n- `meta`: this field is intended for attaching arbitrary Erlang terms to\n  stanzas; the field is represented by a `map()` and can be manipulated\n  using standard [maps](http://erlang.org/doc/man/maps.html) module, but\n  also using the following functions: [get_meta/1](doc/API.md#get_meta1),\n  [get_meta/2](doc/API.md#get_meta2), [get_meta/3](doc/API.md#get_meta3), [set_meta/2](doc/API.md#set_meta2),\n  [put_meta/3](doc/API.md#put_meta3), [update_meta/3](doc/API.md#update_meta3) and\n  [del_meta/2](doc/API.md#del_meta2)\n\n### Constructing stanza responses\n\nFor creating `iq()` replies the following functions exist:\n[make_iq_result/1](doc/API.md#make_iq_result1) and [make_iq_result/2](doc/API.md#make_iq_result2).\n\nThese two functions are `iq()` specific and create `iq()` elements of type\n`result` only. To create an error response from an arbitrary stanza\n(including `iq()`) [make_error/2](doc/API.md#make_error2) function can be used.\n\n## Error elements\n\nA series of functions is provided by `xmpp` module for constructing\n`stanza_error()` or `stream_error()` elements. To construct `stanza_error()`\nelements the functions with `err_` prefix can be used, such as\n[err_bad_request/0](doc/API.md#err_bad_request0) or\n[err_internal_server_error/2](doc/API.md#err_internal_server_error2).\nTo construct `stream_error()` elements the functions with `serr_` prefix\ncan be used, such as [serr_not_well_formed/0](doc/API.md#serr_not_well_formed0) or\n[serr_invalid_from/2](doc/API.md#serr_invalid_from2).\n\n## Text elements\n\nThe text element is represented by `#text{}` record (of `text()` type).\nSome record fields, such as `#message.body` or `#presence.status`,\ncontain a list of text elements (i.e. `[text()]`).\nTo avoid writing a lot of extracting code the following functions can be used\nto manipulate with `text()` elements: [get_text/1](doc/API.md#get_text1),\n[get_text/2](doc/API.md#get_text2), [mk_text/1](doc/API.md#mk_text1) and [mk_text/2](doc/API.md#mk_text2).\n\n## Pretty printer\n\nFor pretty printing of XMPP elements (for example, for dumping elements in\nthe log in a more readable form), [pp/1](doc/API.md#pp1) function can be used.\n\n## Namespaces\n\nThere are many predefined macros for XMPP specific XML namespaces defined\nin [include/ns.hrl](include/ns.hrl) such as `?NS_CLIENT` or `?NS_ROSTER`.\n\n\u003e **WARNING**: you should **not** include `ns.hrl` in your erlang code.\n\u003e Include `xmpp.hrl` instead. Consult this file only to obtain a macro\n\u003e name for the required namespace.\n\nThere is also [get_ns/1](doc/API.md#get_ns1) function which can be used\nto obtain a namespace of `xmpp_element()` or from `xmlel()` element.\n\n## XMPP addresses\n\nAn XMPP address (aka Jabber ID or JID) can be represented using\ntwo types:\n- `jid()`: a JID is represented by a record `#jid{}`.\n  This type is used to represent JIDs in XMPP elements.\n- `ljid()`: a JID is represented by a tuple `{User, Server, Resource}`\n  where `User`, `Server` and `Resource` are stringprepped version of\n  a nodepart, namepart and resourcepart of a JID respectively.\n  This representation is useful for JIDs comparison and when a JID\n  should be used as a key (in a Mnesia database, ETS table, etc.)\n\nBoth types and the record are defined in [include/jid.hrl](include/jid.hrl).\n\n\u003e **WARNING**: you should **not** include `jid.hrl` in your erlang code.\n\u003e Include `xmpp.hrl` instead.\n\nFunctions for working with JIDs are provided by [jid](doc/API.md#jid) module.\n\n## Language translation\n\nThe library uses a callback function in order to perform language\ntranslation. The translation is applied when constructing\n[text](#text-elements) or [error](#error-elements) elements.\nTo set the callback one can use [set_tr_callback/1](doc/API.md#set_tr_callback1)\nfunction. By default, no translation is performed.\n\n# Supported XMPP elements\n\nXMPP elements from the following documents are supported.\nFor more details check the file [xmpp.doap](xmpp.doap)\nand its nice display in [Erlang/Elixir XMPP at xmpp.org](https://xmpp.org/software/erlang-elixir-xmpp/).\n\n- [RFC 6120](https://tools.ietf.org/html/rfc6120): XMPP Core\n- [RFC 6121](https://tools.ietf.org/html/rfc6121): XMPP Instant Messaging and Presence\n- [RFC 9266](https://tools.ietf.org/html/rfc9266): Channel Bindings for TLS 1.3\n- [XEP-0004](https://xmpp.org/extensions/xep-0004.html):  Data Forms\n- [XEP-0012](https://xmpp.org/extensions/xep-0012.html):  Last Activity\n- [XEP-0013](https://xmpp.org/extensions/xep-0013.html):  Flexible Offline Message Retrieval\n- [XEP-0016](https://xmpp.org/extensions/xep-0016.html):  Privacy Lists\n- [XEP-0022](https://xmpp.org/extensions/xep-0022.html):  Message Events\n- [XEP-0023](https://xmpp.org/extensions/xep-0023.html):  Message Expiration\n- [XEP-0030](https://xmpp.org/extensions/xep-0030.html):  Service Discovery\n- [XEP-0033](https://xmpp.org/extensions/xep-0033.html):  Extended Stanza Addressing\n- [XEP-0039](https://xmpp.org/extensions/xep-0039.html):  Statistics Gathering\n- [XEP-0045](https://xmpp.org/extensions/xep-0045.html):  Multi-User Chat\n- [XEP-0047](https://xmpp.org/extensions/xep-0047.html):  In-Band Bytestreams\n- [XEP-0048](https://xmpp.org/extensions/xep-0048.html):  Bookmarks\n- [XEP-0049](https://xmpp.org/extensions/xep-0049.html):  Private XML Storage\n- [XEP-0050](https://xmpp.org/extensions/xep-0050.html):  Ad-Hoc Commands\n- [XEP-0054](https://xmpp.org/extensions/xep-0054.html):  vcard-temp\n- [XEP-0055](https://xmpp.org/extensions/xep-0055.html):  Jabber Search\n- [XEP-0059](https://xmpp.org/extensions/xep-0059.html):  Result Set Management\n- [XEP-0060](https://xmpp.org/extensions/xep-0060.html):  Publish-Subscribe\n- [XEP-0065](https://xmpp.org/extensions/xep-0065.html):  SOCKS5 Bytestreams\n- [XEP-0066](https://xmpp.org/extensions/xep-0066.html):  Out of Band Data\n- [XEP-0077](https://xmpp.org/extensions/xep-0077.html):  In-Band Registration\n- [XEP-0078](https://xmpp.org/extensions/xep-0078.html):  Non-SASL Authentication\n- [XEP-0084](https://xmpp.org/extensions/xep-0084.html):  User Avatar\n- [XEP-0085](https://xmpp.org/extensions/xep-0085.html):  Chat State Notifications\n- [XEP-0092](https://xmpp.org/extensions/xep-0092.html):  Software Version\n- [XEP-0114](https://xmpp.org/extensions/xep-0114.html):  Jabber Component Protocol\n- [XEP-0115](https://xmpp.org/extensions/xep-0115.html):  Entity Capabilities\n- [XEP-0131](https://xmpp.org/extensions/xep-0131.html):  Stanza Headers and Internet Metadata\n- [XEP-0138](https://xmpp.org/extensions/xep-0138.html):  Stream Compression\n- [XEP-0153](https://xmpp.org/extensions/xep-0153.html):  vCard-Based Avatars\n- [XEP-0158](https://xmpp.org/extensions/xep-0158.html):  CAPTCHA Forms\n- [XEP-0166](https://xmpp.org/extensions/xep-0166.html):  Jingle\n- [XEP-0172](https://xmpp.org/extensions/xep-0172.html):  User Nickname\n- [XEP-0184](https://xmpp.org/extensions/xep-0184.html):  Message Delivery Receipts\n- [XEP-0191](https://xmpp.org/extensions/xep-0191.html):  Blocking Command\n- [XEP-0198](https://xmpp.org/extensions/xep-0198.html):  Stream Management\n- [XEP-0199](https://xmpp.org/extensions/xep-0199.html):  XMPP Ping\n- [XEP-0202](https://xmpp.org/extensions/xep-0202.html):  Entity Time\n- [XEP-0203](https://xmpp.org/extensions/xep-0203.html):  Delayed Delivery\n- [XEP-0215](https://xmpp.org/extensions/xep-0215.html):  External Service Discovery\n- [XEP-0220](https://xmpp.org/extensions/xep-0220.html):  Server Dialback\n- [XEP-0221](https://xmpp.org/extensions/xep-0221.html):  Data Forms Media Element\n- [XEP-0231](https://xmpp.org/extensions/xep-0231.html):  Bits of Binary\n- [XEP-0234](https://xmpp.org/extensions/xep-0234.html):  Jingle File Transfer\n- [XEP-0249](https://xmpp.org/extensions/xep-0249.html):  Direct MUC Invitations\n- [XEP-0260](https://xmpp.org/extensions/xep-0260.html):  Jingle SOCKS5 Bytestreams Transport Method\n- [XEP-0261](https://xmpp.org/extensions/xep-0261.html):  Jingle In-Band Bytestreams Transport Method\n- [XEP-0264](https://xmpp.org/extensions/xep-0264.html):  Jingle Content Thumbnails\n- [XEP-0279](https://xmpp.org/extensions/xep-0279.html):  Server IP Check\n- [XEP-0280](https://xmpp.org/extensions/xep-0280.html):  Message Carbons\n- [XEP-0297](https://xmpp.org/extensions/xep-0297.html):  Stanza Forwarding\n- [XEP-0300](https://xmpp.org/extensions/xep-0300.html):  Use of Cryptographic Hash Functions in XMPP\n- [XEP-0313](https://xmpp.org/extensions/xep-0313.html):  Message Archive Management\n- [XEP-0319](https://xmpp.org/extensions/xep-0319.html):  Last User Interaction in Presence\n- [XEP-0328](https://xmpp.org/extensions/xep-0328.html):  JID Prep\n- [XEP-0333](https://xmpp.org/extensions/xep-0333.html):  Chat Markers\n- [XEP-0334](https://xmpp.org/extensions/xep-0334.html):  Message Processing Hints\n- [XEP-0352](https://xmpp.org/extensions/xep-0352.html):  Client State Indication\n- [XEP-0355](https://xmpp.org/extensions/xep-0355.html):  Namespace Delegation\n- [XEP-0356](https://xmpp.org/extensions/xep-0356.html):  Privileged Entity\n- [XEP-0357](https://xmpp.org/extensions/xep-0357.html):  Push Notifications\n- [XEP-0359](https://xmpp.org/extensions/xep-0359.html):  Unique and Stable Stanza IDs\n- [XEP-0363](https://xmpp.org/extensions/xep-0363.html):  HTTP File Upload\n- [XEP-0369](https://xmpp.org/extensions/xep-0369.html):  Mediated Information eXchange (MIX)\n- [XEP-0377](https://xmpp.org/extensions/xep-0377.html):  Spam Reporting\n- [XEP-0386](https://xmpp.org/extensions/xep-0386.html):  Bind 2\n- [XEP-0388](https://xmpp.org/extensions/xep-0388.html):  Extensible SASL Profile\n- [XEP-0402](https://xmpp.org/extensions/xep-0402.html):  PEP Native Bookmarks\n- [XEP-0403](https://xmpp.org/extensions/xep-0403.html):  MIX: Presence Support\n- [XEP-0405](https://xmpp.org/extensions/xep-0405.html):  MIX: Participant Server Requirements\n- [XEP-0417](https://xmpp.org/extensions/xep-0417.html):  E2E Authentication in XMPP: Certificate Issuance and Revocation\n- [XEP-0421](https://xmpp.org/extensions/xep-0421.html):  Anonymous unique occupant identifiers for MUCs\n- [XEP-0422](https://xmpp.org/extensions/xep-0422.html):  Message Fastening\n- [XEP-0424](https://xmpp.org/extensions/xep-0424.html):  Message Retraction\n- [XEP-0425](https://xmpp.org/extensions/xep-0425.html):  Message Moderation\n- [XEP-0430](https://xmpp.org/extensions/xep-0430.html):  Inbox\n- [XEP-0440](https://xmpp.org/extensions/xep-0440.html):  SASL Channel-Binding Type Capability\n- [XEP-0474](https://xmpp.org/extensions/xep-0474.html):  SASL SCRAM Downgrade Protection\n- [draft-cridland-xmpp-session-01](https://tools.ietf.org/html/draft-cridland-xmpp-session-01): XMPP Session Establishment\n\nAs well as some proprietary extensions from [ProcessOne](https://www.process-one.net)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprocessone%2Fxmpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprocessone%2Fxmpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprocessone%2Fxmpp/lists"}