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_clear_headers       (GHashTable        *hash);
 120
 121 typedef enum {
 122         SOUP_HTTP_1_0 = 0,
 123         SOUP_HTTP_1_1 = 1,
 124 } SoupHttpVersion;
 125
 126 void           soup_message_set_http_version    (SoupMessage       *msg,
 127                                                  SoupHttpVersion    version);
 128
 129 void           soup_message_set_context         (SoupMessage       *msg,
 130                                                  SoupContext       *new_ctx);
 131
 132 SoupContext   *soup_message_get_context         (SoupMessage       *msg);
 133
 134 typedef enum {
 135         /*
 136          * SOUP_MESSAGE_NO_PIPELINE:
 137          * Use a currently unused connection or establish a new
 138          * connection when issuing this request.
 139          */
 140         SOUP_MESSAGE_NO_PIPELINE      = (1 << 0),
 141
 142         /*
 143          * SOUP_MESSAGE_NO_REDIRECT:
 144          * Do not follow redirection responses.
 145          */
 146         SOUP_MESSAGE_NO_REDIRECT      = (1 << 1),
 147
 148         /*
 149          * SOUP_MESSAGE_NO_COOKIE:
 150          * Do not send cookie information with request, and do not
 151          * store cookie information from the response.
 152          */
 153         SOUP_MESSAGE_NO_COOKIE        = (1 << 2),
 154
 155         /*
 156          * SOUP_MESSAGE_OVERWRITE_CHUNKS:
 157          * Downloaded data chunks should not be stored in the response
 158          * data buffer.  Instead only send data to SOUP_HANDLER_BODY_CHUNK
 159          * handlers, then truncate the data buffer.
 160          *
 161          * Useful when the response is expected to be very large, and
 162          * storage in memory is not desired.
 163          */
 164         SOUP_MESSAGE_OVERWRITE_CHUNKS = (1 << 3)
 165 } SoupMessageFlags;
 166
 167 void           soup_message_set_flags           (SoupMessage        *msg,
 168                                                  guint               flags);
 169
 170 guint          soup_message_get_flags           (SoupMessage        *msg);
 171
 172 /*
 173  * Handler Registration
 174  */
 175 typedef enum {
 176         SOUP_HANDLER_PRE_BODY = 1,
 177         SOUP_HANDLER_BODY_CHUNK,
 178         SOUP_HANDLER_POST_BODY
 179 } SoupHandlerType;
 180
 181 void           soup_message_add_handler         (SoupMessage       *msg,
 182                                                  SoupHandlerType    type,
 183                                                  SoupCallbackFn     handler_cb,
 184                                                  gpointer           user_data);
 185
 186 void           soup_message_add_header_handler  (SoupMessage       *msg,
 187                                                  const gchar       *header,
 188                                                  SoupHandlerType    type,
 189                                                  SoupCallbackFn     handler_cb,
 190                                                  gpointer           user_data);
 191
 192 void           soup_message_add_error_code_handler (
 193                                                  SoupMessage       *msg,
 194                                                  guint              errorcode,
 195                                                  SoupHandlerType    type,
 196                                                  SoupCallbackFn     handler_cb,
 197                                                  gpointer           user_data);
 198
 199 void           soup_message_add_error_class_handler (
 200                                                  SoupMessage       *msg,
 201                                                  SoupErrorClass     errorclass,
 202                                                  SoupHandlerType    type,
 203                                                  SoupCallbackFn     handler_cb,
 204                                                  gpointer           user_data);
 205
 206 void           soup_message_remove_handler      (SoupMessage       *msg,
 207                                                  SoupHandlerType    type,
 208                                                  SoupCallbackFn     handler_cb,
 209                                                  gpointer           user_data);
 210
 211 /*
 212  * Error Setting (for use by Handlers)
 213  */
 214 void           soup_message_set_error           (SoupMessage       *msg,
 215                                                  SoupKnownErrorCode errcode);
 216
 217 void           soup_message_set_error_full      (SoupMessage       *msg,
 218                                                  guint              errcode,
 219                                                  const gchar       *errphrase);
 220
 221 void           soup_message_set_handler_error   (SoupMessage       *msg,
 222                                                  guint              errcode,
 223                                                  const gchar       *errphrase);
 224
 225 /** DEPRECATED API **/
 226
 227 /** DEPRECATED **/
 228 void           soup_message_set_request_header  (SoupMessage       *req,
 229                                                  const gchar       *name,
 230                                                  const gchar       *value);
 231
 232 /** DEPRECATED **/
 233 const gchar   *soup_message_get_request_header  (SoupMessage       *req,
 234                                                  const gchar       *name);
 235
 236 /** DEPRECATED **/
 237 void           soup_message_set_response_header (SoupMessage       *req,
 238                                                  const gchar       *name,
 239                                                  const gchar       *value);
 240
 241 /** DEPRECATED **/
 242 const gchar   *soup_message_get_response_header (SoupMessage       *req,
 243                                                  const gchar       *name);
 244
 245 #endif /*SOUP_MESSAGE_H*/