1 /* purple 2 * 3 * Purple is the legal property of its developers, whose names are too numerous 4 * to list here. Please refer to the COPYRIGHT file distributed with this 5 * source distribution. 6 * 7 * This program is free software; you can redistribute it and/or modify 8 * it under the terms of the GNU General Public License as published by 9 * the Free Software Foundation; either version 2 of the License, or 10 * (at your option) any later version. 11 * 12 * This program is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 * GNU General Public License for more details. 16 * 17 * You should have received a copy of the GNU General Public License 18 * along with this program; if not, write to the Free Software 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA 20 */ 21 22 #ifndef _PURPLE_SOCKET_H_ 23 #define _PURPLE_SOCKET_H_ 24 /** 25 * SECTION:purple-socket 26 * @section_id: libpurple-purple-socket 27 * @short_description: <filename>purple-socket.h</filename> 28 * @title: Generic Sockets 29 */ 30 31 #include "connection.h" 32 33 /** 34 * PurpleSocket: 35 * 36 * A structure holding all resources needed for the TCP connection. 37 */ 38 typedef struct _PurpleSocket PurpleSocket; 39 40 /** 41 * PurpleSocketConnectCb: 42 * @ps: The socket. 43 * @error: Error message, or NULL if connection was successful. 44 * @user_data: The user data passed with callback function. 45 * 46 * A callback fired after (successfully or not) establishing a connection. 47 */ 48 typedef void (*PurpleSocketConnectCb)(PurpleSocket *ps, const gchar *error, 49 gpointer user_data); 50 51 /** 52 * purple_socket_new: 53 * @gc: The connection for which the socket is needed, or NULL. 54 * 55 * Creates new, disconnected socket. 56 * 57 * Passing a PurpleConnection allows for proper proxy handling. 58 * 59 * Returns: The new socket struct. 60 */ 61 PurpleSocket * 62 purple_socket_new(PurpleConnection *gc); 63 64 /** 65 * purple_socket_get_connection: 66 * @ps: The socket. 67 * 68 * Gets PurpleConnection tied with specified socket. 69 * 70 * Returns: The PurpleConnection object. 71 */ 72 PurpleConnection * 73 purple_socket_get_connection(PurpleSocket *ps); 74 75 /** 76 * purple_socket_set_tls: 77 * @ps: The socket. 78 * @is_tls: TRUE, if TLS should be handled transparently, FALSE otherwise. 79 * 80 * Determines, if socket should handle TLS. 81 */ 82 void 83 purple_socket_set_tls(PurpleSocket *ps, gboolean is_tls); 84 85 /** 86 * purple_socket_set_host: 87 * @ps: The socket. 88 * @host: The connection host. 89 * 90 * Sets connection host. 91 */ 92 void 93 purple_socket_set_host(PurpleSocket *ps, const gchar *host); 94 95 /** 96 * purple_socket_set_port: 97 * @ps: The socket. 98 * @port: The connection port. 99 * 100 * Sets connection port. 101 */ 102 void 103 purple_socket_set_port(PurpleSocket *ps, int port); 104 105 /** 106 * purple_socket_connect: 107 * @ps: The socket. 108 * @cb: The function to call after establishing a connection, or on 109 * error. 110 * @user_data: The user data to be passed to callback function. 111 * 112 * Establishes a connection. 113 * 114 * Returns: TRUE on success (this doesn't mean it's connected yet), FALSE 115 * otherwise. 116 */ 117 gboolean 118 purple_socket_connect(PurpleSocket *ps, PurpleSocketConnectCb cb, 119 gpointer user_data); 120 121 /** 122 * purple_socket_read: 123 * @ps: The socket. 124 * @buf: The buffer to write data to. 125 * @len: The buffer size. 126 * 127 * Reads incoming data from socket. 128 * 129 * This function deals with TLS, if the socket is configured to do it. 130 * 131 * Returns: Amount of data written, or -1 on error (errno will be also be set). 132 */ 133 gssize 134 purple_socket_read(PurpleSocket *ps, guchar *buf, size_t len); 135 136 /** 137 * purple_socket_write: 138 * @ps: The socket. 139 * @buf: The buffer to read data from. 140 * @len: The amount of data to read and send. 141 * 142 * Sends data through socket. 143 * 144 * This function deals with TLS, if the socket is configured to do it. 145 * 146 * Returns: Amount of data sent, or -1 on error (errno will albo be set). 147 */ 148 gssize 149 purple_socket_write(PurpleSocket *ps, const guchar *buf, size_t len); 150 151 /** 152 * purple_socket_watch: 153 * @ps: The socket. 154 * @cond: The condition type. 155 * @func: The callback function for data, or NULL to remove any 156 * existing callbacks. 157 * @user_data: The user data to be passed to callback function. 158 * 159 * Adds an input handler for the socket. 160 * 161 * If the specified socket had input handler already registered, it will be 162 * removed. To remove any input handlers, pass an NULL handler function. 163 */ 164 void 165 purple_socket_watch(PurpleSocket *ps, PurpleInputCondition cond, 166 PurpleInputFunction func, gpointer user_data); 167 168 /** 169 * purple_socket_get_fd: 170 * @ps: The socket 171 * 172 * Gets underlying file descriptor for socket. 173 * 174 * It's not meant to read/write data (use purple_socket_read/ 175 * purple_socket_write), rather for watching for changes with select(). 176 * 177 * Returns: The file descriptor, or -1 on error. 178 */ 179 int 180 purple_socket_get_fd(PurpleSocket *ps); 181 182 /** 183 * purple_socket_set_data: 184 * @ps: The socket. 185 * @key: The unique key. 186 * @data: The data to assign, or NULL to remove. 187 * 188 * Sets extra data for a socket. 189 */ 190 void 191 purple_socket_set_data(PurpleSocket *ps, const gchar *key, gpointer data); 192 193 /** 194 * purple_socket_get_data: 195 * @ps: The socket. 196 * @key: The unqiue key. 197 * 198 * Returns extra data in a socket. 199 * 200 * Returns: The data associated with the key. 201 */ 202 gpointer 203 purple_socket_get_data(PurpleSocket *ps, const gchar *key); 204 205 /** 206 * purple_socket_destroy: 207 * @ps: The socket. 208 * 209 * Destroys the socket, closes connection and frees all resources. 210 * 211 * If file descriptor for the socket was extracted with purple_socket_get_fd and 212 * added to event loop, it have to be removed prior this. 213 */ 214 void 215 purple_socket_destroy(PurpleSocket *ps); 216 217 #endif /* _PURPLE_SOCKET_H_ */ 218