libpurple/protocols/novell/nmconn.h

   1 /*
   2  * nmconn.h
   3  *
   4  * Copyright (c) 2004 Novell, Inc. All Rights Reserved.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; version 2 of the License.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA        02111-1301      USA
  18  *
  19  */
  20
  21 #ifndef PURPLE_NOVELL_NMCONN_H
  22 #define PURPLE_NOVELL_NMCONN_H
  23
  24 typedef struct _NMConn NMConn;
  25 typedef struct _NMSSLConn NMSSLConn;
  26
  27 #include "nmfield.h"
  28 #include "nmuser.h"
  29
  30 typedef int (*nm_ssl_read_cb) (gpointer ssl_data, void *buff, int len);
  31 typedef int (*nm_ssl_write_cb) (gpointer ssl_data, const void *buff, int len);
  32
  33 struct _NMConn
  34 {
  35
  36         /* The address of the server that we are connecting to. */
  37         char *addr;
  38
  39         /* The port that we are connecting to. */
  40         int port;
  41
  42         /* The file descriptor of the socket for the connection. */
  43         int fd;
  44
  45         /* The transaction counter. */
  46         int trans_id;
  47
  48         /* A list of requests currently awaiting a response. */
  49         GSList *requests;
  50
  51         /* Are we connected? TRUE if so, FALSE if not. */
  52         gboolean connected;
  53
  54         /* Are we running in secure mode? */
  55         gboolean use_ssl;
  56
  57         /* Have we been redirected? */
  58         gboolean redirect;
  59
  60         /* SSL connection  */
  61         NMSSLConn *ssl_conn;
  62
  63 };
  64
  65 struct _NMSSLConn
  66 {
  67
  68         /*  Data to pass to the callbacks */
  69         gpointer data;
  70
  71         /* Callbacks for reading/writing */
  72         nm_ssl_read_cb read;
  73         nm_ssl_write_cb write;
  74
  75 };
  76
  77 /**
  78  * Allocate a new NMConn struct
  79  *
  80  * @param       The address of the server that we are connecting to.
  81  * @param       The port that we are connecting to.
  82  *
  83  * @return              A pointer to a newly allocated NMConn struct, should
  84  *                              be freed by calling nm_release_conn()
  85  */
  86 NMConn *nm_create_conn(const char *addr, int port);
  87
  88 /**
  89  * Release an NMConn
  90  *
  91  * @param       Pointer to the NMConn to release.
  92  *
  93  */
  94 void nm_release_conn(NMConn *conn);
  95
  96 /**
  97  * Write len bytes from the given buffer.
  98  *
  99  * @param conn  The connection to write to.
 100  * @param buff  The buffer to write from.
 101  * @param len   The number of bytes to write.
 102  *
 103  * @return              The number of bytes written.
 104  */
 105 int nm_tcp_write(NMConn * conn, const void *buff, int len);
 106
 107 /**
 108  * Read at most len bytes into the given buffer.
 109  *
 110  * @param conn  The connection to read from.
 111  * @param buff  The buffer to write to.
 112  * @param len   The maximum number of bytes to read.
 113  *
 114  * @return              The number of bytes read.
 115  */
 116 int nm_tcp_read(NMConn * conn, void *buff, int len);
 117
 118 /**
 119  * Read exactly len bytes into the given buffer.
 120  *
 121  * @param conn  The connection to read from.
 122  * @param buff  The buffer to write to.
 123  * @param len   The number of bytes to read.
 124  *
 125  * @return              NM_OK on success, NMERR_TCP_READ if read fails.
 126  */
 127 NMERR_T nm_read_all(NMConn * conn, char *buf, int len);
 128
 129 /**
 130  * Read a 32 bit value and convert it to the host byte order.
 131  *
 132  * @param conn  The connection to read from.
 133  * @param val   A pointer to unsigned 32 bit integer
 134  *
 135  * @return              NM_OK on success, NMERR_TCP_READ if read fails.
 136  */
 137 NMERR_T
 138 nm_read_uint32(NMConn *conn, guint32 *val);
 139
 140 /**
 141  * Read a 16 bit value and convert it to the host byte order.
 142  *
 143  * @param conn  The connection to read from.
 144  * @param val   A pointer to unsigned 16 bit integer
 145  *
 146  * @return              NM_OK on success, NMERR_TCP_READ if read fails.
 147  */
 148 NMERR_T
 149 nm_read_uint16(NMConn *conn, guint16 *val);
 150
 151 /**
 152  * Dispatch a request to the server.
 153  *
 154  * @param conn          The connection.
 155  * @param cmd           The request to dispatch.
 156  * @param fields        The field list for the request.
 157  * @param cb            The response callback for the new request object.
 158  * @param data          The user defined data for the request (to be passed to the resp cb).
 159  * @param req           The request. Should be freed with nm_release_request.
 160  *
 161  * @return                      NM_OK on success.
 162  */
 163 NMERR_T
 164 nm_send_request(NMConn *conn, char *cmd, NMField *fields,
 165                                 nm_response_cb cb, gpointer data, NMRequest **request);
 166
 167 /**
 168  * Write out the given field list.
 169  *
 170  * @param conn          The connection to write to.
 171  * @param fields        The field list to write.
 172  *
 173  * @return                      NM_OK on success.
 174  */
 175 NMERR_T nm_write_fields(NMConn * conn, NMField * fields);
 176
 177 /**
 178  * Read the headers for a response.
 179  *
 180  * @param conn          The connection to read from.
 181  *
 182  * @return                      NM_OK on success.
 183  */
 184 NMERR_T nm_read_header(NMConn * conn);
 185
 186 /**
 187  * Read a field list from the connection.
 188  *
 189  * @param conn          The connection to read from.
 190  * @param count         The maximum number of fields to read (or -1 for no max).
 191  * @param fields        The field list. This is an out param. It
 192  *                                      should be freed by calling nm_free_fields
 193  *                                      when finished.
 194  *
 195  * @return                      NM_OK on success.
 196  */
 197 NMERR_T nm_read_fields(NMConn * conn, int count, NMField ** fields);
 198
 199 /**
 200  * Add a request to the connections request list.
 201  *
 202  * @param conn          The connection.
 203  * @param request       The request to add to the list.
 204  */
 205 void nm_conn_add_request_item(NMConn * conn, NMRequest * request);
 206
 207 /**
 208  * Remove a request from the connections list.
 209  *
 210  * @param conn          The connection.
 211  * @param request       The request to remove from the list.
 212  */
 213 void nm_conn_remove_request_item(NMConn * conn, NMRequest * request);
 214
 215 /**
 216  * Find the request with the given transaction id in the connections
 217  * request list.
 218  *
 219  * @param conn          The connection.
 220  * @param trans_id      The transaction id of the request to return.
 221  *
 222  * @return                      The request, or NULL if a matching request is not
 223  *                                      found.
 224  */
 225 NMRequest *nm_conn_find_request(NMConn * conn, int trans_id);
 226
 227 /**
 228  * Get the server address for the connection.
 229  *
 230  * @param conn          The connection.
 231  *
 232  * @return                      The server address for the connection.
 233  *
 234  */
 235 const char *nm_conn_get_addr(NMConn * conn);
 236
 237 /**
 238  * Get the port for the connection.
 239  *
 240  * @param conn          The connection.
 241  *
 242  * @return                      The port that we are connected to.
 243  */
 244 int nm_conn_get_port(NMConn * conn);
 245
 246 #endif /* PURPLE_NOVELL_NMCONN_H */