lutjanus XMPP lib
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 

418 lines
11 KiB

/* lutjanus.h - So 24. Jan 07:42:22 CET 2021
*
* vim: expandtab:ts=2:sts=2:sw=2
*
* Copyright (C) 2021 DebXWoody <stefan@devlug.de>
*
* This file is part of liblutjanus.
*
* liblutjanus is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* liblutjanus is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with buteo. If not, see <http://www.gnu.org/licenses/>.
*/
/*!
* \file lutjanus.h
* \brief The lutjanus API.
*
* \mainpage
*
* lutjanus is a C library build common functions and implementation of XEPs
* based on libstrophe.
*
* - Address: \ref address
* - Account: \ref account
* - Roster: \ref roster
*
* \page address XMPP Address
* \brief The XMPP Address
*
* The address (lutjanus_xmpp_adr_t).
*
* \page account XMPP Account
* \brief The XMPP Account
*
* The account ( lutjanus_xmpp_account_t ) holds the libstrophe context and connection.
* The account has got a roster ( lutjanus_roster_t ) which is the
*
* \page roster XMPP Roster
* \brief The XMPP contact list
*
* The roster ( lutjanus_roster_t ) is the contact list of a account.
*
* \copyright Copyright (C) 2021 DebXWoody <stefan@devlug.de>
*/
#ifndef LUTJANUS_H__
#define LUTJANUS_H__
#include <glib.h>
#include <strophe.h>
typedef char* stanza_id_t;
// ----------------------------------------------------------------------------
// XMPP Address
// ----------------------------------------------------------------------------
/*!
* \brief The XMPP address
*
* A lutjanus_xmpp_adr_t is XMPP address with local part, domain part and optionally a resource part.
*
* Create this object via \ref lutjanus_xmpp_adr_new
*
*
* \author DebXWoody <stefan@devlug.de>
* \copyright Copyright (C) 2021 DebXWoody <stefan@devlug.de>
*/
typedef struct _lutjanus_xmpp_adr_t lutjanus_xmpp_adr_t;
/*!
* \brief Creates a new XMPP-Address
* \param local local_part of the address
* \param domain domain_part of the address
* \param resource resource_part of the address or NULL for bare XMPP Addresses
*/
lutjanus_xmpp_adr_t *lutjanus_xmpp_adr_new(GString *local, GString *domain,
GString *resource);
/*!
* \brief Parse XMPP Address String
*
* \param address GString reference with XMPP address
* \return XMPP Address struct
*/
lutjanus_xmpp_adr_t *lutjanus_xmpp_adr_new_parse(const GString *const address);
/*!
* \brief Get the bare XMPP address.
*
* \param address a XMPP address
* \returns new allocated GString with the bare XMPP-Address ( local@domain )
*/
GString *lutjanus_xmpp_adr_get_bare(const lutjanus_xmpp_adr_t *const address);
/*!
* \brief Get the full XMPP address.
*
* \param address a XMPP address
* \returns new allocated GString with the full XMPP-Address (local@domain/resource )
*/
GString *lutjanus_xmpp_adr_get_full(const lutjanus_xmpp_adr_t *const address);
/*!
* \brief Compare full XMPP addresses
*
* \param adr1 XMPP address
* \param adr2 XMPP address
*
* \returns TURE, when the addresses are the same.
*/
gboolean lutjanus_xmpp_adr_compare(const lutjanus_xmpp_adr_t *const adr1,
const lutjanus_xmpp_adr_t *const adr2);
/*!
* \brief Compare bare XMPP addresses
*
* \param adr1 XMPP address
* \param adr2 XMPP address
*
* \returns TURE, when the addresses are the same.
*/
gboolean lutjanus_xmpp_adr_compare_bare(const lutjanus_xmpp_adr_t *const adr1,
const lutjanus_xmpp_adr_t *const adr2);
// ----------------------------------------------------------------------------
// XMPP Account
// ----------------------------------------------------------------------------
/*!
* \brief The XMPP Account.
*
* Create this object via \ref lutjanus_xmpp_account_new.
*/
typedef struct _lutjanus_xmpp_account_t lutjanus_xmpp_account_t;
/*!
* \brief Creates a new XMPP account.
*
* Allocates a lutjanus_xmpp_account_t object and stores the address and libstrophe context.
*
* \param adr The XMPP address of the account.
* \param ctx the libstrophe context
*
*/
lutjanus_xmpp_account_t *lutjanus_xmpp_account_new(lutjanus_xmpp_adr_t* adr, xmpp_ctx_t *ctx);
/*!
* \brief Sets the libstrophe connection
*
* \param account The XMPP address of the account.
* \param conn The connection.
*/
void lutjanus_set_xmpp_connection(lutjanus_xmpp_account_t* account, xmpp_conn_t *conn );
// ----------------------------------------------------------------------------
// XMPP Presence
// ----------------------------------------------------------------------------
/*!
* \brief types of presence
*
* Defined in
* https://tools.ietf.org/html/rfc6121#section-4.7.1
*/
typedef enum {
/*! available */
LUTJANUS_PRESENCE_AVAILABLE = 0,
/*! error */
LUTJANUS_PRESENCE_ERROR = 1,
/*! subscribe */
LUTJANUS_PRESENCE_SUBSCRIBE = 2,
/*! subscribed */
LUTJANUS_PRESENCE_SUBSCRIBED = 3,
/*! unavailable */
LUTJANUS_PRESENCE_UNAVAILABLE = 4,
/*! unsubscribe */
LUTJANUS_PRESENCE_UNSUBSCRIBE = 5,
/*! unsubscribed */
LUTJANUS_PRESENCE_UNSUBSCRIBED = 6
} lutjanus_presence_type_t;
/*!
* \brief Show presence
*
*/
typedef enum {
/*! unknown */
LUTJANUS_PRESENCE_UNKNOWN = 0,
/*! online */
LUTJANUS_PRESENCE_ONLINE = 1,
/*! away */
LUTJANUS_PRESENCE_AWAY = 2,
/*! chat */
LUTJANUS_PRESENCE_CHAT = 3,
/*! dnd */
LUTJANUS_PRESENCE_DND = 4,
/*! extended away */
LUTJANUS_PRESENCE_XA = 5,
} lutjanus_presence_show_t;
/*!
* \brief presence
*
*/
typedef struct _lutjanus_presence_t lutjanus_presence_t;
/*!
* \brief Create a new presence
*
* \param from
* \param type
* \param show
* \param text
*
* \returns new allocated presence.
*/
lutjanus_presence_t *lutjanus_presence_new(lutjanus_xmpp_adr_t *from,
lutjanus_presence_type_t type,
lutjanus_presence_show_t show, GString *text);
lutjanus_xmpp_adr_t * lutjanus_presence_from(lutjanus_presence_t * presence);
// ----------------------------------------------------------------------------
// XMPP Contact
// ----------------------------------------------------------------------------
/*!
* \brief Contact list ( roster )
*/
typedef struct _lutjanus_roster_t lutjanus_roster_t;
/*!
* \brief A contact ( buddy )
*/
typedef struct lutjanus_buddy_t lutjanus_buddy_t;
// ----------------------------------------------------------------------------
// XMPP Message
// ----------------------------------------------------------------------------
/*!
* \brief A message
*/
typedef struct _lutjanus_message_t lutjanus_message_t;
/*!
* \brief Creates a new message
*
* \returns new allocated message.
*/
lutjanus_message_t *lutjanus_xmpp_message_new(lutjanus_xmpp_adr_t* to, GString* text);
lutjanus_xmpp_adr_t * lutjanus_xmpp_message_from(lutjanus_message_t* message);
lutjanus_xmpp_adr_t * lutjanus_xmpp_message_to(lutjanus_message_t* message);
GString* lutjanus_xmpp_message_text(lutjanus_message_t* message);
// ----------------------------------------------------------------------------
// XMPP Groupchat
// ----------------------------------------------------------------------------
/*!
* \brief XMPP Multi User chat (groupchat).
*
*/
typedef struct _lutjanus_groupchat_t lutjanus_groupchat_t;
/*!
* \brief Creates a new XMPP-Address
* \param address Groupchat's XMPP address
* \return new allocated group chat struct
*/
lutjanus_groupchat_t *lutjanus_xmpp_groupchat_new(lutjanus_xmpp_adr_t *const address);
/*!
* \brief Join the groupchat.
* \param account lutjanus conect
* \param groupchat Groupchat
*/
void lutjanus_xmpp_groupchat_join(const lutjanus_xmpp_account_t *const account, const lutjanus_groupchat_t *const groupchat);
/*!
* \brief Gets the XMPP Address of a groupchat
*
* \param groupchat The groupchat
* \returns the Address of the groupchat
*/
lutjanus_xmpp_adr_t * lutjanus_xmpp_groupchat_get_adr(const lutjanus_groupchat_t *const groupchat);
/*!
* \brief Returns the name of the groupchat
*
* \param groupchat The groupchat
* \returns the name of the groupchat
*/
GString *
lutjanus_xmpp_groupchat_get_name(const lutjanus_groupchat_t *const groupchat);
/*!
* \brief Returns the nickname of the account within the groupchat.
*
* \param groupchat The groupchat
* \returns the nickname
*/
GString *
lutjanus_xmpp_groupchat_get_nick(const lutjanus_groupchat_t *const groupchat);
/*!
* \brief Returns a list of messages
*
* \param groupchat The groupchat
* \returns List of pointer to lutjanus_message_t
*/
GList *lutjanus_xmpp_groupchat_messages(const lutjanus_groupchat_t *const groupchat);
/*!
* \brief Returns a list of presences
*
* \param groupchat The groupchat
* \returns List of pointer to lutjanus_presence_t
*/
GList *lutjanus_xmpp_groupchat_presences(const lutjanus_groupchat_t *const groupchat);
/*!
* \brief Handel a incoming message
*
* The message will be stored within the groupchat
*
* \param groupchat The groupchat
* \param message the message
*
*/
void lutjanus_xmpp_groupchat_receive_message(lutjanus_groupchat_t *const groupchat,
lutjanus_message_t *message);
/*!
* \brief Handel a incoming presence
*
* The presence of the buddy will be updated.
*
* \param groupchat The groupchat
* \param presence The presence
*
*/
void lutjanus_xmpp_groupchat_receive_presence(
const lutjanus_groupchat_t *const groupchat, lutjanus_presence_t *presence);
// ----------------------------------------------------------------------------
// Core
// ----------------------------------------------------------------------------
/*!
* \page core lutjanus core
*
* \brief The core framework of lutjanus
*
* The core framework of lutjanus can be used to handle stanzas along with an account.
*
*/
/*!
* \brief lutjanus stanza
*/
typedef struct _lutjanus_xmpp_stanza_t lutjanus_xmpp_stanza_t;
lutjanus_xmpp_stanza_t* lutjanus_create_stanza();
/*!
* \brief lutjanus stanza callback
*
*/
typedef void (*lutjanus_stanza_result_cb_t)(xmpp_stanza_t *stanza, void *const obj, void *const userdata);
/*!
* \brief lutjanus fire stanza and let it manage by the callback
*
*/
void lutjanus_fire_and_handle(lutjanus_xmpp_account_t* account, lutjanus_xmpp_stanza_t* lutjanus_stanza, lutjanus_stanza_result_cb_t callback, void *const userdata);
void lutjanus_create_message(lutjanus_xmpp_stanza_t* lutjanus_stanza, lutjanus_xmpp_account_t* account, lutjanus_message_t* message);
// ----------------------------------------------------------------------------
// XEP-0048 Bookmarks
// ----------------------------------------------------------------------------
typedef struct _lutjanus_bookmark_t lutjanus_bookmark_t;
lutjanus_bookmark_t* lutjanus_create_new_bookmark(lutjanus_xmpp_adr_t *adr, GString* name, gboolean autojoin);
void lutjanus_load_bookmarks(lutjanus_xmpp_account_t* account, lutjanus_stanza_result_cb_t callback, void *const userdata);
void lutjanus_create_bookmarks_callback(xmpp_stanza_t *stanza, void *const obj, void *const userdata);
#endif // LUTJANUS_H__