libsoup/soup-message.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
   2 /*
   3  * soup-message.h: Asyncronous Callback-based SOAP Request Queue.
   4  *
   5  * Authors:
   6  *      Alex Graveley (alex@ximian.com)
   7  *
   8  * Copyright (C) 2000, Ximian, Inc.
   9  */
  10
  11 #ifndef SOUP_MESSAGE_H
  12 #define SOUP_MESSAGE_H 1
  13
  14 #include <glib.h>
  15 #include <libsoup/soup-context.h>
  16 #include <libsoup/soup-error.h>
  17
  18 typedef enum {
  19         SOUP_STATUS_IDLE = 0,
  20         SOUP_STATUS_QUEUED,
  21         SOUP_STATUS_CONNECTING,
  22         SOUP_STATUS_SENDING_REQUEST,
  23         SOUP_STATUS_READING_RESPONSE,
  24         SOUP_STATUS_FINISHED
  25 } SoupTransferStatus;
  26
  27 typedef enum {
  28         SOUP_BUFFER_SYSTEM_OWNED = 0,
  29         SOUP_BUFFER_USER_OWNED,
  30         SOUP_BUFFER_STATIC
  31 } SoupOwnership;
  32
  33 typedef struct {
  34         SoupOwnership  owner;
  35         gchar         *body;
  36         guint          length;
  37 } SoupDataBuffer;
  38
  39 #define SOUP_METHOD_POST      "POST"
  40 #define SOUP_METHOD_GET       "GET"
  41 #define SOUP_METHOD_HEAD      "HEAD"
  42 #define SOUP_METHOD_OPTIONS   "OPTIONS"
  43 #define SOUP_METHOD_PUT       "PUT"
  44 #define SOUP_METHOD_MOVE      "MOVE"
  45 #define SOUP_METHOD_COPY      "COPY"
  46 #define SOUP_METHOD_DELETE    "DELETE"
  47 #define SOUP_METHOD_TRACE     "TRACE"
  48 #define SOUP_METHOD_CONNECT   "CONNECT"
  49 #define SOUP_METHOD_MKCOL     "MKCOL"
  50 #define SOUP_METHOD_PROPPATCH "PROPPATCH"
  51 #define SOUP_METHOD_PROPFIND  "PROPFIND"
  52 #define SOUP_METHOD_SEARCH    "SEARCH"
  53
  54 typedef struct _SoupMessage        SoupMessage;
  55 typedef struct _SoupMessagePrivate SoupMessagePrivate;
  56
  57 struct _SoupMessage {
  58         SoupMessagePrivate *priv;
  59
  60         SoupContext        *context;
  61         SoupConnection     *connection;
  62
  63         const gchar        *method;
  64
  65         SoupTransferStatus  status;
  66
  67         guint               errorcode;
  68         SoupErrorClass      errorclass;
  69         const gchar        *errorphrase;
  70
  71         SoupDataBuffer      request;
  72         GHashTable         *request_headers;
  73
  74         SoupDataBuffer      response;
  75         GHashTable         *response_headers;
  76 };
  77
  78 #define SOUP_MESSAGE_IS_ERROR(_msg)                            \
  79         (_msg->errorclass &&                                   \
  80          _msg->errorclass != SOUP_ERROR_CLASS_SUCCESS &&       \
  81          _msg->errorclass != SOUP_ERROR_CLASS_INFORMATIONAL && \
  82          _msg->errorclass != SOUP_ERROR_CLASS_UNKNOWN)
  83
  84 typedef void (*SoupCallbackFn) (SoupMessage *req, gpointer user_data);
  85
  86 SoupMessage   *soup_message_new                 (SoupContext       *context,
  87                                                  const gchar       *method);
  88
  89 SoupMessage   *soup_message_new_full            (SoupContext       *context,
  90                                                  const gchar       *method,
  91                                                  SoupOwnership      req_owner,
  92                                                  gchar             *req_body,
  93                                                  gulong             req_length);
  94
  95 void           soup_message_free                (SoupMessage       *req);
  96
  97 void           soup_message_cancel              (SoupMessage       *req);
  98
  99 SoupErrorClass soup_message_send                (SoupMessage       *msg);
 100
 101 void           soup_message_queue               (SoupMessage       *req,
 102                                                  SoupCallbackFn     callback,
 103                                                  gpointer           user_data);
 104
 105 void           soup_message_add_header          (GHashTable        *hash,
 106                                                  const gchar       *name,
 107                                                  const gchar       *value);
 108
 109 const gchar   *soup_message_get_header          (GHashTable        *hash,
 110                                                  const gchar       *name);
 111
 112 const GSList  *soup_message_get_header_list     (GHashTable        *hash,
 113                                                  const gchar       *name);
 114
 115 void           soup_message_foreach_header      (GHashTable        *hash,
 116                                                  GHFunc             func,
 117                                                  gpointer           user_data);
 118
 119 void           soup_message_foreach_remove_header (
 120                                                  GHashTable        *hash,
 121                                                  GHRFunc            func,
 122                                                  gpointer           user_data);
 123
 124 void           soup_message_remove_header       (GHashTable        *hash,
 125                                                  const gchar       *name);
 126
 127 void           soup_message_clear_headers       (GHashTable        *hash);
 128
 129 typedef enum {
 130         SOUP_HTTP_1_0 = 0,
 131         SOUP_HTTP_1_1 = 1,
 132 } SoupHttpVersion;
 133
 134 void           soup_message_set_http_version    (SoupMessage       *msg,
 135                                                  SoupHttpVersion    version);
 136
 137 SoupHttpVersion soup_message_get_http_version   (SoupMessage       *msg);
 138
 139 void           soup_message_set_context         (SoupMessage       *msg,
 140                                                  SoupContext       *new_ctx);
 141
 142 SoupContext   *soup_message_get_context         (SoupMessage       *msg);
 143
 144 typedef enum {
 145         /*
 146          * SOUP_MESSAGE_NO_PIPELINE:
 147          * Use a currently unused connection or establish a new
 148          * connection when issuing this request.
 149          */
 150         SOUP_MESSAGE_NO_PIPELINE      = (1 << 0),
 151
 152         /*
 153          * SOUP_MESSAGE_NO_REDIRECT:
 154          * Do not follow redirection responses.
 155          */
 156         SOUP_MESSAGE_NO_REDIRECT      = (1 << 1),
 157
 158         /*
 159          * SOUP_MESSAGE_NO_COOKIE:
 160          * Do not send cookie information with request, and do not
 161          * store cookie information from the response.
 162          */
 163         SOUP_MESSAGE_NO_COOKIE        = (1 << 2),
 164
 165         /*
 166          * SOUP_MESSAGE_OVERWRITE_CHUNKS:
 167          * Downloaded data chunks should not be stored in the response
 168          * data buffer.  Instead only send data to SOUP_HANDLER_BODY_CHUNK
 169          * handlers, then truncate the data buffer.
 170          *
 171          * Useful when the response is expected to be very large, and
 172          * storage in memory is not desired.
 173          */
 174         SOUP_MESSAGE_OVERWRITE_CHUNKS = (1 << 3)
 175 } SoupMessageFlags;
 176
 177 void           soup_message_set_flags           (SoupMessage        *msg,
 178                                                  guint               flags);
 179
 180 guint          soup_message_get_flags           (SoupMessage        *msg);
 181
 182 /*
 183  * Handler Registration
 184  */
 185 typedef enum {
 186         /*
 187          * Client-side events
 188          */
 189         SOUP_HANDLER_PREPARE = 0,
 190         SOUP_HANDLER_HEADERS,
 191         SOUP_HANDLER_DATA,
 192         SOUP_HANDLER_FINISHED,
 193
 194         /*
 195          * Server-side events
 196          */
 197         SOUP_HANDLER_DATA_SENT
 198 } SoupHandlerEvent;
 199
 200 enum {
 201         SOUP_FILTER_HEADER      = (1 << 0),
 202         SOUP_FILTER_ERROR_CODE  = (1 << 1),
 203         SOUP_FILTER_ERROR_CLASS = (1 << 2),
 204         SOUP_FILTER_TIMEOUT     = (1 << 3),
 205 } SoupHandlerFilterType;
 206
 207 typedef struct {
 208         gint type;
 209
 210         union {
 211                 guint               errorcode;
 212                 SoupErrorClass      errorclass;
 213                 const gchar        *header;
 214                 guint               timeout;
 215         } data;
 216 } SoupHandlerFilter;
 217
 218 typedef enum {
 219         /*
 220          * Continue processing as normal.
 221          */
 222         SOUP_HANDLER_CONTINUE,
 223
 224         /*
 225          * Do not process further handlers.  Continue receiving data.
 226          */
 227         SOUP_HANDLER_STOP,
 228
 229         /*
 230          * do not process further handlers.  Stop receiving data and
 231          * issue final callback.
 232          */
 233         SOUP_HANDLER_KILL,
 234
 235         /*
 236          * Restart handler processing.  This should be returned if a
 237          * handler changes the message's errorcode.
 238          */
 239         SOUP_HANDLER_RESTART,
 240
 241         /*
 242          * Requeue the request immediately.  Stop processing handlers
 243          * and do not issue final callback.
 244          */
 245         SOUP_HANDLER_RESEND
 246 } SoupHandlerResult;
 247
 248 typedef SoupHandlerResult (*SoupHandlerFn) (SoupMessage *req,
 249                                             gpointer     user_data);
 250
 251 void           soup_message_add_handler         (SoupMessage       *msg,
 252                                                  SoupHandlerEvent   type,
 253                                                  SoupHandlerFilter *filter,
 254                                                  SoupHandlerFn      handler_cb,
 255                                                  gpointer           user_data);
 256
 257 typedef enum {
 258         /*
 259          * Run before global handlers and previously registered message
 260          * handlers.
 261          */
 262         SOUP_HANDLER_FIRST,
 263
 264         /*
 265          * Run after global handlers and previously registered message
 266          * handlers.
 267          */
 268         SOUP_HANDLER_LAST
 269 } SoupHandlerWhen;
 270
 271 void           soup_message_add_handler_full    (SoupMessage       *msg,
 272                                                  const gchar       *name,
 273                                                  SoupHandlerEvent   type,
 274                                                  SoupHandlerWhen    order,
 275                                                  SoupHandlerFilter *filter,
 276                                                  SoupHandlerFn      handler_cb,
 277                                                  gpointer           user_data);
 278
 279 GSList        *soup_message_list_handlers       (SoupMessage       *msg);
 280
 281 void           soup_message_remove_handler      (SoupMessage       *msg,
 282                                                  gchar             *name);
 283
 284 void           soup_message_remove_handler_by_func (
 285                                                  SoupMessage       *msg,
 286                                                  SoupHandlerFn      handler_cb);
 287
 288 void           soup_message_remove_handler_by_func_and_data (
 289                                                  SoupMessage       *msg,
 290                                                  SoupHandlerFn      handler_cb,
 291                                                  gpointer           user_data);
 292
 293 /*
 294  * Error Setting (for use by Handlers)
 295  */
 296 void           soup_message_set_error           (SoupMessage       *msg,
 297                                                  SoupKnownErrorCode errcode);
 298
 299 void           soup_message_set_error_full      (SoupMessage       *msg,
 300                                                  guint              errcode,
 301                                                  const gchar       *errphrase);
 302
 303 void           soup_message_set_handler_error   (SoupMessage       *msg,
 304                                                  guint              errcode,
 305                                                  const gchar       *errphrase);
 306
 307 #endif /*SOUP_MESSAGE_H*/