eion/purple-hangouts
Merge
draft
2019-05-24, Eion Robb
* 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 * 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, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA #ifndef _PURPLE_SOCKET_H_ #define _PURPLE_SOCKET_H_ * @section_id: libpurple-purple-socket * @short_description: <filename>purple-socket.h</filename> * @title: Generic Sockets * A structure holding all resources needed for the TCP connection. typedef struct _PurpleSocket PurpleSocket; * @error: Error message, or NULL if connection was successful. * @user_data: The user data passed with callback function. * A callback fired after (successfully or not) establishing a connection. typedef void (*PurpleSocketConnectCb)(PurpleSocket *ps, const gchar *error, * @gc: The connection for which the socket is needed, or NULL. * Creates new, disconnected socket. * Passing a PurpleConnection allows for proper proxy handling. * Returns: The new socket struct. purple_socket_new(PurpleConnection *gc); * purple_socket_get_connection: * Gets PurpleConnection tied with specified socket. * Returns: The PurpleConnection object. purple_socket_get_connection(PurpleSocket *ps); * @is_tls: TRUE, if TLS should be handled transparently, FALSE otherwise. * Determines, if socket should handle TLS. purple_socket_set_tls(PurpleSocket *ps, gboolean is_tls); * purple_socket_set_host: * @host: The connection host. purple_socket_set_host(PurpleSocket *ps, const gchar *host); * purple_socket_set_port: * @port: The connection port. purple_socket_set_port(PurpleSocket *ps, int port); * @cb: The function to call after establishing a connection, or on * @user_data: The user data to be passed to callback function. * Establishes a connection. * Returns: TRUE on success (this doesn't mean it's connected yet), FALSE purple_socket_connect(PurpleSocket *ps, PurpleSocketConnectCb cb, * @buf: The buffer to write data to. * Reads incoming data from socket. * This function deals with TLS, if the socket is configured to do it. * Returns: Amount of data written, or -1 on error (errno will be also be set). purple_socket_read(PurpleSocket *ps, guchar *buf, size_t len); * @buf: The buffer to read data from. * @len: The amount of data to read and send. * Sends data through socket. * This function deals with TLS, if the socket is configured to do it. * Returns: Amount of data sent, or -1 on error (errno will albo be set). purple_socket_write(PurpleSocket *ps, const guchar *buf, size_t len); * @cond: The condition type. * @func: The callback function for data, or NULL to remove any * @user_data: The user data to be passed to callback function. * Adds an input handler for the socket. * If the specified socket had input handler already registered, it will be * removed. To remove any input handlers, pass an NULL handler function. purple_socket_watch(PurpleSocket *ps, PurpleInputCondition cond, PurpleInputFunction func, gpointer user_data); * Gets underlying file descriptor for socket. * It's not meant to read/write data (use purple_socket_read/ * purple_socket_write), rather for watching for changes with select(). * Returns: The file descriptor, or -1 on error. purple_socket_get_fd(PurpleSocket *ps); * purple_socket_set_data: * @data: The data to assign, or NULL to remove. * Sets extra data for a socket. purple_socket_set_data(PurpleSocket *ps, const gchar *key, gpointer data); * purple_socket_get_data: * Returns extra data in a socket. * Returns: The data associated with the key. purple_socket_get_data(PurpleSocket *ps, const gchar *key); * Destroys the socket, closes connection and frees all resources. * If file descriptor for the socket was extracted with purple_socket_get_fd and * added to event loop, it have to be removed prior this. purple_socket_destroy(PurpleSocket *ps); #endif /* _PURPLE_SOCKET_H_ */