pidgin/pidgin

Ignore pidginprivate.h from the docs

2021-05-13, Gary Kramlich
1b5b70f24f62
Ignore pidginprivate.h from the docs

Testing Done:
Ran docs locally, had to remove the html and xml directories to have a clean build.

Reviewed at https://reviews.imfreedom.org/r/653/
/*
* Purple - Internet Messaging Library
* Copyright (C) Pidgin Developers <devel@pidgin.im>
*
* Purple is the legal property of its developers, whose names are too numerous
* to list here. Please refer to the COPYRIGHT file distributed with this
* source distribution.
*
* This program 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 2 of the License, or
* (at your option) any later version.
*
* This program 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 this program; if not, see <https://www.gnu.org/licenses/>.
*/
#if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
# error "only <purple.h> may be included directly"
#endif
#ifndef PURPLE_PROTOCOL_SERVER_H
#define PURPLE_PROTOCOL_SERVER_H
/**
* SECTION:purpleprotocolserver
* @section_id: libpurple-purpleprotocolserver
* @short_description: Protocol Server Interface
* @title: ProtocolServer Interface
*
* #PurpleProtocolServer describes the API for protocols that have a central
* server.
*/
#include <glib.h>
#include <glib-object.h>
#include <libpurple/account.h>
#include <libpurple/buddy.h>
#include <libpurple/connection.h>
#include <libpurple/group.h>
#include <libpurple/purplemessage.h>
#define PURPLE_TYPE_PROTOCOL_SERVER (purple_protocol_server_get_type())
G_DECLARE_INTERFACE(PurpleProtocolServer, purple_protocol_server, PURPLE,
PROTOCOL_SERVER, GObject)
G_BEGIN_DECLS
/**
* PURPLE_TYPE_PROTOCOL_SERVER:
*
* The standard _get_type method for #PurpleProtocolServer.
*
* Since: 3.0.0
*/
/**
* PurpleProtocolServer:
*
* An opaque data structure used to reference a #PurpleProtocol that implements
* #PurpleProtocolServerInterface.
*
* Since: 3.0.0
*/
/**
* PurpleProtocolServerInterface:
* @register_user: Register a new user.
* @unregister_user: Remove the user from the server. The account can either be
* connected or disconnected. After the removal is finished,
* the connection will stay open and has to be closed!
* @set_info: Sets the user's profile.
* @get_info: Should arrange for purple_notify_userinfo() to be called with the
* requested user's profile.
* @set_status: Sets the active status for the given account.
* @set_idle: Set the idle time for the given account.
* @change_passwd: Changes the users password.
* @add_buddy: Add a buddy to a group on the server.
* @add_buddies: Add multiple buddies on the server at once.
* @remove_buddy: Removes the given buddy from the user's buddy list.
* @remove_buddies: Removes multiple buddies from the user's buddy list.
* @keepalive: If implemented, this will be called regularly for this
* protocol's active connections. You'd want to do this if you need
* to repeatedly send some kind of keepalive packet to the server
* to avoid being disconnected. ("Regularly" is defined to be 30
* unless @get_keepalive_interval is implemented to override it).
* @get_keepalive_interval: If implemented, this will override the default
* keepalive interval.
* @alias_buddy: Save/store buddy's alias on server list/roster
* @group_buddy: Change a buddy's group on a server list/roster
* @rename_group: Rename a group on a server list/roster
* @set_buddy_icon: Set the buddy icon for the given connection to @img. The
* protocol does <emphasis>NOT</emphasis> own a reference to
* @img; if it needs one, it must #g_object_ref(@img) itself.
* @remove_group: Removes the given group from the users buddy list.
* @send_raw: For use in plugins that may understand the underlying protocol.
*
* The protocol server interface.
*
* This interface provides a gateway between purple and the protocol's server.
*/
struct _PurpleProtocolServerInterface {
/*< private >*/
GTypeInterface parent;
/*< public >*/
void (*register_user)(PurpleProtocolServer *protocol_server, PurpleAccount *account);
void (*unregister_user)(PurpleProtocolServer *protocol_server, PurpleAccount *account, PurpleAccountUnregistrationCb cb, gpointer data);
void (*set_info)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *info);
void (*get_info)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *who);
void (*set_status)(PurpleProtocolServer *protocol_server, PurpleAccount *account, PurpleStatus *status);
void (*set_idle)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, gint idletime);
void (*change_passwd)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *old_pass, const gchar *new_pass);
void (*add_buddy)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, PurpleBuddy *buddy, PurpleGroup *group, const gchar *message);
void (*add_buddies)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, GList *buddies, GList *groups, const gchar *message);
void (*remove_buddy)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, PurpleBuddy *buddy, PurpleGroup *group);
void (*remove_buddies)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, GList *buddies, GList *groups);
void (*keepalive)(PurpleProtocolServer *protocol_server, PurpleConnection *connection);
gint (*get_keepalive_interval)(PurpleProtocolServer *protocol_server);
void (*alias_buddy)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *who, const gchar *alias);
void (*group_buddy)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *who, const gchar *old_group, const gchar *new_group);
void (*rename_group)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *old_name, PurpleGroup *group, GList *moved_buddies);
void (*set_buddy_icon)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, PurpleImage *img);
void (*remove_group)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, PurpleGroup *group);
gint (*send_raw)(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *buf, gint len);
/*< private >*/
gpointer reserved[8];
};
/**
* purple_protocol_server_register_user:
* @protocol_server: The #PurpleProtocolServer instance.
* @account: The #PurpleAccount to register.
*
* Tell @protocol_server to register the new account described by @account.
*
* Since: 3.0.0
*/
void purple_protocol_server_register_user(PurpleProtocolServer *protocol_server, PurpleAccount *account);
/**
* purple_protocol_server_unregister_user:
* @protocol_server: The #PurpleProtocolServer instance.
* @account: The #PurpleAccount instance.
* @cb: (scope call): A PurpleAccountUnregistrationCb function.
* @data: User data to pass to @cb.
*
* Unregisters @account with @protocol_server. The account can either be
* connected or disconnected. After the removal is finished, the connection
* will stay open and has to be closed.
*
* Since: 3.0.0
*/
void purple_protocol_server_unregister_user(PurpleProtocolServer *protocol_server, PurpleAccount *account, PurpleAccountUnregistrationCb cb, gpointer data);
/**
* purple_protocol_server_set_info:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @info: The user info to set.
*
* Sets the user info, sometimes referred to as a user profile to @info.
*
* Since: 3.0.0
*/
void purple_protocol_server_set_info(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *info);
/**
* purple_protocol_server_get_info:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @who: The name of the user whose information you're asking for.
*
* Gets the user info or profile for @who and displays it in a protocol specifc
* way.
*
* Since: 3.0.0
*/
void purple_protocol_server_get_info(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *who);
/**
* purple_protocol_server_set_status:
* @protocol_server: The #PurpleProtocolServer instance.
* @account: The #PurpleAccount instance.
* @status: The #PurpleStatus instance.
*
* Sets the status for account @account to @status.
*
* Since: 3.0.0
*/
void purple_protocol_server_set_status(PurpleProtocolServer *protocol_server, PurpleAccount *account, PurpleStatus *status);
/**
* purple_protocol_server_set_idle:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @idletime: The number of seconds that the user has been idle.
*
* Tells @protocol_server to set the user's idle time to @idletime.
*
* Since: 3.0.0
*/
void purple_protocol_server_set_idle(PurpleProtocolServer *protocol_server, PurpleConnection *connection, gint idletime);
/**
* purple_protocol_server_change_passwd:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @old_pass: The user's old password.
* @new_pass: The new password for the user.
*
* Changes the user's password from @old_pass to @new_pass.
*
* Since: 3.0.0
*/
void purple_protocol_server_change_passwd(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *old_pass, const gchar *new_pass);
/**
* purple_protocol_server_add_buddy:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @buddy: The #PurpleBuddy to add.
* @group: The #PurpleGroup for @buddy.
* @message: An optional invite message.
*
* This protocol function may be called in situations in which the buddy is
* already in the specified group. If the protocol supports authorization and
* the user is not already authorized to see the status of @buddy, this
* function will request authorization. If authorization is required, then
* @message will be used as an invite message.
*
* Since: 3.0.0
*/
void purple_protocol_server_add_buddy(PurpleProtocolServer *protocol_server, PurpleConnection *connection, PurpleBuddy *buddy, PurpleGroup *group, const gchar *message);
/**
* purple_protocol_server_add_buddies:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @buddies: (element-type PurpleBuddy): A #GList of #PurpleBuddy's to add.
* @groups: (element-type PurpleGroup): A #GList of #PurpleGroup's that
* correspond to the @buddies parameter.
* @message: An optional invite message to send.
*
* Similar to purple_protocol_server_add_buddy() but can add multiple buddies
* at a time. If @protocol_server does not implement this function, this will
* call purple_protocol_server_add_buddy() for each buddy/group pair in
* @buddies/@groups.
*
* Since: 3.0.0
*/
void purple_protocol_server_add_buddies(PurpleProtocolServer *protocol_server, PurpleConnection *connection, GList *buddies, GList *groups, const gchar *message);
/**
* purple_protocol_server_remove_buddy:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @buddy: The #PurpleBuddy instance.
* @group: (nullable): The #PurpleGroup instance.
*
* Removes @buddy and potentially @group from the server side list of contacts.
*
* Since: 3.0.0
*/
void purple_protocol_server_remove_buddy(PurpleProtocolServer *protocol_server, PurpleConnection *connection, PurpleBuddy *buddy, PurpleGroup *group);
/**
* purple_protocol_server_remove_buddies:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @buddies: (element-type PurpleBuddy): A #GList of #PurpleBuddy's to remove.
* @groups: (element-type PurpleGroup): A #GList of #PurpleGroup's
* corresponding to @buddies.
*
* Similiar to purple_protocol_server_remove_buddy() but allows you to remove
* multiple at a time.
*
* If @protocol_server doesn't implement this function directly,
* purple_protocol_server_remove_buddy() will be called for each buddy/group
* pair in @buddies/@groups.
*
* Since: 3.0.0
*/
void purple_protocol_server_remove_buddies(PurpleProtocolServer *protocol_server, PurpleConnection *connection, GList *buddies, GList *groups);
/**
* purple_protocol_server_keepalive:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
*
* Tell @protocol_server to send its keep alive to the server.
*
* Since: 3.0.0
*/
void purple_protocol_server_keepalive(PurpleProtocolServer *protocol_server, PurpleConnection *connection);
/**
* purple_protocol_server_get_keepalive_interval:
* @protocol_server: The #PurpleProtocolServer instance.
*
* Returns a custom interval, in seconds, that libpurple should tell
* @protocol_server to send its keepalive.
*
* Returns: The interval, in seconds, that the keep-alive function should be
* called.
*
* Since: 3.0.0
*/
gint purple_protocol_server_get_keepalive_interval(PurpleProtocolServer *protocol_server);
/**
* purple_protocol_server_alias_buddy:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @who: The name of the user to alias.
* @alias: The new alias for @who.
*
* Sets the server side alias for @who to @alias.
*
* Since: 3.0.0
*/
void purple_protocol_server_alias_buddy(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *who, const gchar *alias);
/**
* purple_protocol_server_group_buddy:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @who: The name of the user whose group to switch.
* @old_group: The name of @who's old group.
* @new_group: The name of the new group to add @who to.
*
* Moves @who from group @old_group to a new group of @new_group.
*
* Since: 3.0.0
*/
void purple_protocol_server_group_buddy(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *who, const gchar *old_group, const gchar *new_group);
/**
* purple_protocol_server_rename_group:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @old_name: The old name of the group.
* @group: The new #PurpleGroup instance.
* @moved_buddies: (element-type PurpleBuddy): A list of #PurpleBuddy's being
* moved as part of this rename.
*
* Renames the group named @old_name to the new @group.
*
* Since: 3.0.0
*/
void purple_protocol_server_rename_group(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *old_name, PurpleGroup *group, GList *moved_buddies);
/**
* purple_protocol_server_set_buddy_icon:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @img: (nullable): The #PurpleImage instance, or %NULL to unset the icon.
*
* Sets the user's buddy icon to @img.
*
* Since: 3.0.0
*/
void purple_protocol_server_set_buddy_icon(PurpleProtocolServer *protocol_server, PurpleConnection *connection, PurpleImage *img);
/**
* purple_protocol_server_remove_group:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @group: The #PurpleGroup instance.
*
* Removes @group from the server side contact list.
*
* Since: 3.0.0
*/
void purple_protocol_server_remove_group(PurpleProtocolServer *protocol_server, PurpleConnection *connection, PurpleGroup *group);
/**
* purple_protocol_server_send_raw:
* @protocol_server: The #PurpleProtocolServer instance.
* @connection: The #PurpleConnection instance.
* @buf: The raw protocol data to send.
* @len: The length of @buf in bytes.
*
* Sends raw data over the protocol. This should only be called when you know
* the exact underlying protocol.
*
* Returns: The number of bytes that was sent.
*
* Since: 3.0.0
*/
gint purple_protocol_server_send_raw(PurpleProtocolServer *protocol_server, PurpleConnection *connection, const gchar *buf, gint len);
G_END_DECLS
#endif /* PURPLE_PROTOCOL_SERVER_H */