libsoup/soup-message.c

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
   2 /*
   3  * soup-message.c: HTTP request/response
   4  *
   5  * Copyright (C) 2000-2003, Ximian, Inc.
   6  */
   7
   8 #include <stdlib.h>
   9 #include <string.h>
  10
  11 #include "soup-auth.h"
  12 #include "soup-marshal.h"
  13 #include "soup-message.h"
  14 #include "soup-message-private.h"
  15 #include "soup-misc.h"
  16 #include "soup-server-message.h"
  17 #include "soup-uri.h"
  18
  19 G_DEFINE_TYPE (SoupMessage, soup_message, G_TYPE_OBJECT)
  20
  21 enum {
  22         WROTE_INFORMATIONAL,
  23         WROTE_HEADERS,
  24         WROTE_CHUNK,
  25         WROTE_BODY,
  26
  27         GOT_INFORMATIONAL,
  28         GOT_HEADERS,
  29         GOT_CHUNK,
  30         GOT_BODY,
  31
  32         RESTARTED,
  33         FINISHED,
  34
  35         LAST_SIGNAL
  36 };
  37
  38 static guint signals[LAST_SIGNAL] = { 0 };
  39
  40 static void wrote_body (SoupMessage *req);
  41 static void got_headers (SoupMessage *req);
  42 static void got_chunk (SoupMessage *req);
  43 static void got_body (SoupMessage *req);
  44 static void restarted (SoupMessage *req);
  45 static void finished (SoupMessage *req);
  46 static void free_chunks (SoupMessage *msg);
  47
  48 static void
  49 soup_message_init (SoupMessage *msg)
  50 {
  51         msg->status  = SOUP_MESSAGE_STATUS_IDLE;
  52
  53         msg->request_headers = g_hash_table_new (soup_str_case_hash,
  54                                                  soup_str_case_equal);
  55
  56         msg->response_headers = g_hash_table_new (soup_str_case_hash,
  57                                                   soup_str_case_equal);
  58
  59         SOUP_MESSAGE_GET_PRIVATE (msg)->http_version = SOUP_HTTP_1_1;
  60 }
  61
  62 static void
  63 finalize (GObject *object)
  64 {
  65         SoupMessage *msg = SOUP_MESSAGE (object);
  66         SoupMessagePrivate *priv = SOUP_MESSAGE_GET_PRIVATE (msg);
  67
  68         soup_message_io_stop (msg);
  69
  70         if (priv->uri)
  71                 soup_uri_free (priv->uri);
  72
  73         if (priv->auth)
  74                 g_object_unref (priv->auth);
  75         if (priv->proxy_auth)
  76                 g_object_unref (priv->proxy_auth);
  77
  78         if (msg->request.owner == SOUP_BUFFER_SYSTEM_OWNED)
  79                 g_free (msg->request.body);
  80         if (msg->response.owner == SOUP_BUFFER_SYSTEM_OWNED)
  81                 g_free (msg->response.body);
  82         free_chunks (msg);
  83
  84         soup_message_clear_headers (msg->request_headers);
  85         g_hash_table_destroy (msg->request_headers);
  86
  87         soup_message_clear_headers (msg->response_headers);
  88         g_hash_table_destroy (msg->response_headers);
  89
  90         g_slist_foreach (priv->content_handlers, (GFunc) g_free, NULL);
  91         g_slist_free (priv->content_handlers);
  92
  93         g_free ((char *) msg->reason_phrase);
  94
  95         G_OBJECT_CLASS (soup_message_parent_class)->finalize (object);
  96 }
  97
  98 static void
  99 soup_message_class_init (SoupMessageClass *message_class)
 100 {
 101         GObjectClass *object_class = G_OBJECT_CLASS (message_class);
 102
 103         g_type_class_add_private (message_class, sizeof (SoupMessagePrivate));
 104
 105         /* virtual method definition */
 106         message_class->wrote_body   = wrote_body;
 107         message_class->got_headers  = got_headers;
 108         message_class->got_chunk    = got_chunk;
 109         message_class->got_body     = got_body;
 110         message_class->restarted    = restarted;
 111         message_class->finished     = finished;
 112
 113         /* virtual method override */
 114         object_class->finalize = finalize;
 115
 116         /* signals */
 117
 118         /**
 119          * SoupMessage::wrote-informational:
 120          * @msg: the message
 121          *
 122          * Emitted immediately after writing a 1xx (Informational)
 123          * response for a message.
 124          **/
 125         signals[WROTE_INFORMATIONAL] =
 126                 g_signal_new ("wrote_informational",
 127                               G_OBJECT_CLASS_TYPE (object_class),
 128                               G_SIGNAL_RUN_FIRST,
 129                               G_STRUCT_OFFSET (SoupMessageClass, wrote_informational),
 130                               NULL, NULL,
 131                               soup_marshal_NONE__NONE,
 132                               G_TYPE_NONE, 0);
 133
 134         /**
 135          * SoupMessage::wrote-headers:
 136          * @msg: the message
 137          *
 138          * Emitted immediately after writing the headers for a message.
 139          **/
 140         signals[WROTE_HEADERS] =
 141                 g_signal_new ("wrote_headers",
 142                               G_OBJECT_CLASS_TYPE (object_class),
 143                               G_SIGNAL_RUN_FIRST,
 144                               G_STRUCT_OFFSET (SoupMessageClass, wrote_headers),
 145                               NULL, NULL,
 146                               soup_marshal_NONE__NONE,
 147                               G_TYPE_NONE, 0);
 148
 149         /**
 150          * SoupMessage::wrote-chunk:
 151          * @msg: the message
 152          *
 153          * Emitted immediately after writing a body chunk for a message.
 154          * (This is
 155          **/
 156         signals[WROTE_CHUNK] =
 157                 g_signal_new ("wrote_chunk",
 158                               G_OBJECT_CLASS_TYPE (object_class),
 159                               G_SIGNAL_RUN_FIRST,
 160                               G_STRUCT_OFFSET (SoupMessageClass, wrote_chunk),
 161                               NULL, NULL,
 162                               soup_marshal_NONE__NONE,
 163                               G_TYPE_NONE, 0);
 164
 165         /**
 166          * SoupMessage::wrote-body:
 167          * @msg: the message
 168          *
 169          * Emitted immediately after writing the complete body for a message.
 170          **/
 171         signals[WROTE_BODY] =
 172                 g_signal_new ("wrote_body",
 173                               G_OBJECT_CLASS_TYPE (object_class),
 174                               G_SIGNAL_RUN_FIRST,
 175                               G_STRUCT_OFFSET (SoupMessageClass, wrote_body),
 176                               NULL, NULL,
 177                               soup_marshal_NONE__NONE,
 178                               G_TYPE_NONE, 0);
 179
 180         /**
 181          * SoupMessage::got-informational:
 182          * @msg: the message
 183          *
 184          * Emitted after receiving a 1xx (Informational) response for
 185          * a message.
 186          **/
 187         signals[GOT_INFORMATIONAL] =
 188                 g_signal_new ("got_informational",
 189                               G_OBJECT_CLASS_TYPE (object_class),
 190                               G_SIGNAL_RUN_FIRST,
 191                               G_STRUCT_OFFSET (SoupMessageClass, got_informational),
 192                               NULL, NULL,
 193                               soup_marshal_NONE__NONE,
 194                               G_TYPE_NONE, 0);
 195
 196         /**
 197          * SoupMessage::got-headers:
 198          * @msg: the message
 199          *
 200          * Emitted after receiving all message headers for a message.
 201          **/
 202         signals[GOT_HEADERS] =
 203                 g_signal_new ("got_headers",
 204                               G_OBJECT_CLASS_TYPE (object_class),
 205                               G_SIGNAL_RUN_FIRST,
 206                               G_STRUCT_OFFSET (SoupMessageClass, got_headers),
 207                               NULL, NULL,
 208                               soup_marshal_NONE__NONE,
 209                               G_TYPE_NONE, 0);
 210
 211         /**
 212          * SoupMessage::got-chunk:
 213          * @msg: the message
 214          *
 215          * Emitted after receiving a chunk of a message body. Note
 216          * that "chunk" in this context means any subpiece of the
 217          * body, not necessarily the specific HTTP 1.1 chunks sent by
 218          * the other side.
 219          **/
 220         signals[GOT_CHUNK] =
 221                 g_signal_new ("got_chunk",
 222                               G_OBJECT_CLASS_TYPE (object_class),
 223                               G_SIGNAL_RUN_FIRST,
 224                               G_STRUCT_OFFSET (SoupMessageClass, got_chunk),
 225                               NULL, NULL,
 226                               soup_marshal_NONE__NONE,
 227                               G_TYPE_NONE, 0);
 228
 229         /**
 230          * SoupMessage::got-body:
 231          * @msg: the message
 232          *
 233          * Emitted after receiving the complete message body.
 234          **/
 235         signals[GOT_BODY] =
 236                 g_signal_new ("got_body",
 237                               G_OBJECT_CLASS_TYPE (object_class),
 238                               G_SIGNAL_RUN_FIRST,
 239                               G_STRUCT_OFFSET (SoupMessageClass, got_body),
 240                               NULL, NULL,
 241                               soup_marshal_NONE__NONE,
 242                               G_TYPE_NONE, 0);
 243
 244         /**
 245          * SoupMessage::restarted:
 246          * @msg: the message
 247          *
 248          * Emitted when a message is about to be re-queued.
 249          **/
 250         signals[RESTARTED] =
 251                 g_signal_new ("restarted",
 252                               G_OBJECT_CLASS_TYPE (object_class),
 253                               G_SIGNAL_RUN_FIRST,
 254                               G_STRUCT_OFFSET (SoupMessageClass, restarted),
 255                               NULL, NULL,
 256                               soup_marshal_NONE__NONE,
 257                               G_TYPE_NONE, 0);
 258
 259         /**
 260          * SoupMessage::finished:
 261          * @msg: the message
 262          *
 263          * Emitted when all HTTP processing is finished for a message.
 264          * (After #read-body for client-side code, or after
 265          * #wrote-body for server-side code.)
 266          **/
 267         signals[FINISHED] =
 268                 g_signal_new ("finished",
 269                               G_OBJECT_CLASS_TYPE (object_class),
 270                               G_SIGNAL_RUN_FIRST,
 271                               G_STRUCT_OFFSET (SoupMessageClass, finished),
 272                               NULL, NULL,
 273                               soup_marshal_NONE__NONE,
 274                               G_TYPE_NONE, 0);
 275 }
 276
 277
 278 /**
 279  * soup_message_new:
 280  * @method: the HTTP method for the created request
 281  * @uri_string: the destination endpoint (as a string)
 282  *
 283  * Creates a new empty #SoupMessage, which will connect to @uri
 284  *
 285  * Return value: the new #SoupMessage (or %NULL if @uri could not
 286  * be parsed).
 287  */
 288 SoupMessage *
 289 soup_message_new (const char *method, const char *uri_string)
 290 {
 291         SoupMessage *msg;
 292         SoupUri *uri;
 293
 294         uri = soup_uri_new (uri_string);
 295         if (!uri)
 296                 return NULL;
 297
 298         if (!uri->host) {
 299                 soup_uri_free (uri);
 300                 return NULL;
 301         }
 302
 303         msg = g_object_new (SOUP_TYPE_MESSAGE, NULL);
 304         msg->method = method ? method : SOUP_METHOD_GET;
 305         SOUP_MESSAGE_GET_PRIVATE (msg)->uri = uri;
 306
 307         return msg;
 308 }
 309
 310 /**
 311  * soup_message_new_from_uri:
 312  * @method: the HTTP method for the created request
 313  * @uri: the destination endpoint (as a #SoupUri)
 314  *
 315  * Creates a new empty #SoupMessage, which will connect to @uri
 316  *
 317  * Return value: the new #SoupMessage
 318  */
 319 SoupMessage *
 320 soup_message_new_from_uri (const char *method, const SoupUri *uri)
 321 {
 322         SoupMessage *msg;
 323
 324         msg = g_object_new (SOUP_TYPE_MESSAGE, NULL);
 325         msg->method = method ? method : SOUP_METHOD_GET;
 326         SOUP_MESSAGE_GET_PRIVATE (msg)->uri = soup_uri_copy (uri);
 327
 328         return msg;
 329 }
 330
 331 /**
 332  * soup_message_set_request:
 333  * @msg: the message
 334  * @content_type: MIME Content-Type of the body
 335  * @req_owner: the #SoupOwnership of the passed data buffer.
 336  * @req_body: a data buffer containing the body of the message request.
 337  * @req_length: the byte length of @req_body.
 338  *
 339  * Convenience function to set the request body of a #SoupMessage
 340  */
 341 void
 342 soup_message_set_request (SoupMessage   *msg,
 343                           const char    *content_type,
 344                           SoupOwnership  req_owner,
 345                           char          *req_body,
 346                           gulong         req_length)
 347 {
 348         g_return_if_fail (SOUP_IS_MESSAGE (msg));
 349         g_return_if_fail (content_type != NULL);
 350         g_return_if_fail (req_body != NULL || req_length == 0);
 351
 352         soup_message_add_header (msg->request_headers,
 353                                  "Content-Type", content_type);
 354         msg->request.owner = req_owner;
 355         msg->request.body = req_body;
 356         msg->request.length = req_length;
 357 }
 358
 359 /**
 360  * soup_message_set_response:
 361  * @msg: the message
 362  * @content_type: MIME Content-Type of the body
 363  * @resp_owner: the #SoupOwnership of the passed data buffer.
 364  * @resp_body: a data buffer containing the body of the message response.
 365  * @resp_length: the byte length of @resp_body.
 366  *
 367  * Convenience function to set the response body of a #SoupMessage
 368  */
 369 void
 370 soup_message_set_response (SoupMessage   *msg,
 371                            const char    *content_type,
 372                            SoupOwnership  resp_owner,
 373                            char          *resp_body,
 374                            gulong         resp_length)
 375 {
 376         g_return_if_fail (SOUP_IS_MESSAGE (msg));
 377         g_return_if_fail (content_type != NULL);
 378         g_return_if_fail (resp_body != NULL || resp_length == 0);
 379
 380         soup_message_add_header (msg->response_headers,
 381                                  "Content-Type", content_type);
 382         msg->response.owner = resp_owner;
 383         msg->response.body = resp_body;
 384         msg->response.length = resp_length;
 385 }
 386
 387 /**
 388  * soup_message_wrote_informational:
 389  * @msg: a #SoupMessage
 390  *
 391  * Emits the %wrote_informational signal, indicating that the IO layer
 392  * finished writing an informational (1xx) response for @msg.
 393  **/
 394 void
 395 soup_message_wrote_informational (SoupMessage *msg)
 396 {
 397         g_signal_emit (msg, signals[WROTE_INFORMATIONAL], 0);
 398 }
 399
 400 /**
 401  * soup_message_wrote_headers:
 402  * @msg: a #SoupMessage
 403  *
 404  * Emits the %wrote_headers signal, indicating that the IO layer
 405  * finished writing the (non-informational) headers for @msg.
 406  **/
 407 void
 408 soup_message_wrote_headers (SoupMessage *msg)
 409 {
 410         g_signal_emit (msg, signals[WROTE_HEADERS], 0);
 411 }
 412
 413 /**
 414  * soup_message_wrote_chunk:
 415  * @msg: a #SoupMessage
 416  *
 417  * Emits the %wrote_chunk signal, indicating that the IO layer
 418  * finished writing a chunk of @msg's body.
 419  **/
 420 void
 421 soup_message_wrote_chunk (SoupMessage *msg)
 422 {
 423         g_signal_emit (msg, signals[WROTE_CHUNK], 0);
 424 }
 425
 426 static void
 427 wrote_body (SoupMessage *req)
 428 {
 429         g_object_ref (req);
 430         soup_message_run_handlers (req, SOUP_HANDLER_POST_REQUEST);
 431         g_object_unref (req);
 432 }
 433
 434 /**
 435  * soup_message_wrote_body:
 436  * @msg: a #SoupMessage
 437  *
 438  * Emits the %wrote_body signal, indicating that the IO layer finished
 439  * writing the body for @msg.
 440  **/
 441 void
 442 soup_message_wrote_body (SoupMessage *msg)
 443 {
 444         g_signal_emit (msg, signals[WROTE_BODY], 0);
 445 }
 446
 447 /**
 448  * soup_message_got_informational:
 449  * @msg: a #SoupMessage
 450  *
 451  * Emits the %got_informational signal, indicating that the IO layer
 452  * read a complete informational (1xx) response for @msg.
 453  **/
 454 void
 455 soup_message_got_informational (SoupMessage *msg)
 456 {
 457         g_signal_emit (msg, signals[GOT_INFORMATIONAL], 0);
 458 }
 459
 460 static void
 461 got_headers (SoupMessage *req)
 462 {
 463         g_object_ref (req);
 464         soup_message_run_handlers (req, SOUP_HANDLER_PRE_BODY);
 465         if (SOUP_MESSAGE_IS_STARTING (req))
 466                 g_signal_stop_emission (req, signals[GOT_HEADERS], 0);
 467         g_object_unref (req);
 468 }
 469
 470 /**
 471  * soup_message_got_headers:
 472  * @msg: a #SoupMessage
 473  *
 474  * Emits the %got_headers signal, indicating that the IO layer
 475  * finished reading the (non-informational) headers for @msg.
 476  **/
 477 void
 478 soup_message_got_headers (SoupMessage *msg)
 479 {
 480         g_signal_emit (msg, signals[GOT_HEADERS], 0);
 481 }
 482
 483 static void
 484 got_chunk (SoupMessage *req)
 485 {
 486         g_object_ref (req);
 487         soup_message_run_handlers (req, SOUP_HANDLER_BODY_CHUNK);
 488         if (SOUP_MESSAGE_IS_STARTING (req))
 489                 g_signal_stop_emission (req, signals[GOT_CHUNK], 0);
 490         g_object_unref (req);
 491 }
 492
 493 /**
 494  * soup_message_got_chunk:
 495  * @msg: a #SoupMessage
 496  *
 497  * Emits the %got_chunk signal, indicating that the IO layer finished
 498  * reading a chunk of @msg's body.
 499  **/
 500 void
 501 soup_message_got_chunk (SoupMessage *msg)
 502 {
 503         g_signal_emit (msg, signals[GOT_CHUNK], 0);
 504 }
 505
 506 static void
 507 got_body (SoupMessage *req)
 508 {
 509         g_object_ref (req);
 510         soup_message_run_handlers (req, SOUP_HANDLER_POST_BODY);
 511         if (SOUP_MESSAGE_IS_STARTING (req))
 512                 g_signal_stop_emission (req, signals[GOT_BODY], 0);
 513         g_object_unref (req);
 514 }
 515
 516 /**
 517  * soup_message_got_body:
 518  * @msg: a #SoupMessage
 519  *
 520  * Emits the %got_body signal, indicating that the IO layer finished
 521  * reading the body for @msg.
 522  **/
 523 void
 524 soup_message_got_body (SoupMessage *msg)
 525 {
 526         g_signal_emit (msg, signals[GOT_BODY], 0);
 527 }
 528
 529 static void
 530 restarted (SoupMessage *req)
 531 {
 532         soup_message_io_stop (req);
 533 }
 534
 535 /**
 536  * soup_message_restarted:
 537  * @msg: a #SoupMessage
 538  *
 539  * Emits the %restarted signal, indicating that @msg should be
 540  * requeued.
 541  **/
 542 void
 543 soup_message_restarted (SoupMessage *msg)
 544 {
 545         g_signal_emit (msg, signals[RESTARTED], 0);
 546 }
 547
 548 static void
 549 finished (SoupMessage *req)
 550 {
 551         soup_message_io_stop (req);
 552         req->status = SOUP_MESSAGE_STATUS_FINISHED;
 553 }
 554
 555 /**
 556  * soup_message_finished:
 557  * @msg: a #SoupMessage
 558  *
 559  * Emits the %finished signal, indicating that @msg has been completely
 560  * processed.
 561  **/
 562 void
 563 soup_message_finished (SoupMessage *msg)
 564 {
 565         g_signal_emit (msg, signals[FINISHED], 0);
 566 }
 567
 568 static gboolean
 569 free_header_list (gpointer name, gpointer vals, gpointer user_data)
 570 {
 571         g_free (name);
 572         g_slist_foreach (vals, (GFunc) g_free, NULL);
 573         g_slist_free (vals);
 574
 575         return TRUE;
 576 }
 577
 578 /**
 579  * soup_message_clear_headers:
 580  * @hash: a header table (the %request_headers or %response_headers
 581  * field of a #SoupMessage)
 582  *
 583  * Clears @hash.
 584  **/
 585 void
 586 soup_message_clear_headers (GHashTable *hash)
 587 {
 588         g_return_if_fail (hash != NULL);
 589
 590         g_hash_table_foreach_remove (hash, free_header_list, NULL);
 591 }
 592
 593 /**
 594  * soup_message_remove_header:
 595  * @hash: a header table (the %request_headers or %response_headers
 596  * field of a #SoupMessage)
 597  * @name: the header name to remove
 598  *
 599  * Removes @name from @hash. If there are multiple values for @name,
 600  * they are all removed.
 601  **/
 602 void
 603 soup_message_remove_header (GHashTable *hash, const char *name)
 604 {
 605         gpointer old_key, old_vals;
 606
 607         g_return_if_fail (hash != NULL);
 608         g_return_if_fail (name != NULL || name[0] != '\0');
 609
 610         if (g_hash_table_lookup_extended (hash, name, &old_key, &old_vals)) {
 611                 g_hash_table_remove (hash, name);
 612                 free_header_list (old_key, old_vals, NULL);
 613         }
 614 }
 615
 616 /**
 617  * soup_message_add_header:
 618  * @hash: a header table (the %request_headers or %response_headers
 619  * field of a #SoupMessage)
 620  * @name: the header name to add
 621  * @value: the value of the new header
 622  *
 623  * Adds a header with name @name and value @value to @hash. If there
 624  * was already a header with name @name, this one does not replace it,
 625  * it is merely added to it.
 626  **/
 627 void
 628 soup_message_add_header (GHashTable *hash, const char *name, const char *value)
 629 {
 630         GSList *old_value;
 631
 632         g_return_if_fail (hash != NULL);
 633         g_return_if_fail (name != NULL || name [0] != '\0');
 634         g_return_if_fail (value != NULL);
 635
 636         old_value = g_hash_table_lookup (hash, name);
 637
 638         if (old_value)
 639                 old_value = g_slist_append (old_value, g_strdup (value));
 640         else {
 641                 g_hash_table_insert (hash, g_strdup (name),
 642                                      g_slist_append (NULL, g_strdup (value)));
 643         }
 644 }
 645
 646 /**
 647  * soup_message_get_header:
 648  * @hash: a header table (the %request_headers or %response_headers
 649  * field of a #SoupMessage)
 650  * @name: header name.
 651  *
 652  * Finds the first header in @hash with name @name.
 653  *
 654  * Return value: the header's value or %NULL if not found.
 655  **/
 656 const char *
 657 soup_message_get_header (GHashTable *hash, const char *name)
 658 {
 659         GSList *vals;
 660
 661         g_return_val_if_fail (hash != NULL, NULL);
 662         g_return_val_if_fail (name != NULL || name [0] != '\0', NULL);
 663
 664         vals = g_hash_table_lookup (hash, name);
 665         if (vals)
 666                 return vals->data;
 667
 668         return NULL;
 669 }
 670
 671 /**
 672  * soup_message_get_header_list:
 673  * @hash: a header table (the %request_headers or %response_headers
 674  * field of a #SoupMessage)
 675  * @name: header name.
 676  *
 677  * Finds all headers in @hash with name @name.
 678  *
 679  * Return value: a (possibly empty) list of values of headers with
 680  * name @name. The caller should not modify or free this list.
 681  **/
 682 const GSList *
 683 soup_message_get_header_list (GHashTable *hash, const char *name)
 684 {
 685         g_return_val_if_fail (hash != NULL, NULL);
 686         g_return_val_if_fail (name != NULL || name [0] != '\0', NULL);
 687
 688         return g_hash_table_lookup (hash, name);
 689 }
 690
 691 typedef struct {
 692         GHFunc   func;
 693         gpointer user_data;
 694 } SoupMessageForeachHeaderData;
 695
 696 static void
 697 foreach_value_in_list (gpointer name, gpointer value, gpointer user_data)
 698 {
 699         GSList *vals = value;
 700         SoupMessageForeachHeaderData *data = user_data;
 701
 702         while (vals) {
 703                 (*data->func) (name, vals->data, data->user_data);
 704                 vals = vals->next;
 705         }
 706 }
 707
 708 /**
 709  * soup_message_foreach_header:
 710  * @hash: a header table (the %request_headers or %response_headers
 711  * field of a #SoupMessage)
 712  * @func: callback function to run for each header
 713  * @user_data: data to pass to @func
 714  *
 715  * Calls @func once for each header value in @hash. (If there are
 716  * headers will multiple values, @func will be called once on each
 717  * value.)
 718  **/
 719 void
 720 soup_message_foreach_header (GHashTable *hash, GHFunc func, gpointer user_data)
 721 {
 722         SoupMessageForeachHeaderData data;
 723
 724         g_return_if_fail (hash != NULL);
 725         g_return_if_fail (func != NULL);
 726
 727         data.func = func;
 728         data.user_data = user_data;
 729         g_hash_table_foreach (hash, foreach_value_in_list, &data);
 730 }
 731
 732 /**
 733  * soup_message_set_auth:
 734  * @msg: a #SoupMessage
 735  * @auth: a #SoupAuth, or %NULL
 736  *
 737  * Sets @msg to authenticate to its destination using @auth, which
 738  * must have already been fully authenticated. If @auth is %NULL, @msg
 739  * will not authenticate to its destination.
 740  **/
 741 void
 742 soup_message_set_auth (SoupMessage *msg, SoupAuth *auth)
 743 {
 744         SoupMessagePrivate *priv;
 745         char *token;
 746
 747         g_return_if_fail (SOUP_IS_MESSAGE (msg));
 748         g_return_if_fail (auth == NULL || SOUP_IS_AUTH (auth));
 749         g_return_if_fail (auth == NULL || soup_auth_is_authenticated (auth));
 750
 751         priv = SOUP_MESSAGE_GET_PRIVATE (msg);
 752
 753         if (priv->auth)
 754                 g_object_unref (priv->auth);
 755         soup_message_remove_header (msg->request_headers, "Authorization");
 756         priv->auth = auth;
 757         if (!priv->auth)
 758                 return;
 759
 760         g_object_ref (priv->auth);
 761         token = soup_auth_get_authorization (auth, msg);
 762         soup_message_add_header (msg->request_headers, "Authorization", token);
 763         g_free (token);
 764 }
 765
 766 /**
 767  * soup_message_get_auth:
 768  * @msg: a #SoupMessage
 769  *
 770  * Gets the #SoupAuth used by @msg for authentication.
 771  *
 772  * Return value: the #SoupAuth used by @msg for authentication, or
 773  * %NULL if @msg is unauthenticated.
 774  **/
 775 SoupAuth *
 776 soup_message_get_auth (SoupMessage *msg)
 777 {
 778         g_return_val_if_fail (SOUP_IS_MESSAGE (msg), NULL);
 779
 780         return SOUP_MESSAGE_GET_PRIVATE (msg)->auth;
 781 }
 782
 783 /**
 784  * soup_message_set_proxy_auth:
 785  * @msg: a #SoupMessage
 786  * @auth: a #SoupAuth, or %NULL
 787  *
 788  * Sets @msg to authenticate to its proxy using @auth, which must have
 789  * already been fully authenticated. If @auth is %NULL, @msg will not
 790  * authenticate to its proxy.
 791  **/
 792 void
 793 soup_message_set_proxy_auth (SoupMessage *msg, SoupAuth *auth)
 794 {
 795         SoupMessagePrivate *priv;
 796         char *token;
 797
 798         g_return_if_fail (SOUP_IS_MESSAGE (msg));
 799         g_return_if_fail (auth == NULL || SOUP_IS_AUTH (auth));
 800         g_return_if_fail (auth == NULL || soup_auth_is_authenticated (auth));
 801
 802         priv = SOUP_MESSAGE_GET_PRIVATE (msg);
 803
 804         if (priv->proxy_auth)
 805                 g_object_unref (priv->proxy_auth);
 806         soup_message_remove_header (msg->request_headers,
 807                                     "Proxy-Authorization");
 808         priv->proxy_auth = auth;
 809         if (!priv->proxy_auth)
 810                 return;
 811
 812         g_object_ref (priv->proxy_auth);
 813         token = soup_auth_get_authorization (auth, msg);
 814         soup_message_add_header (msg->request_headers,
 815                                  "Proxy-Authorization", token);
 816         g_free (token);
 817 }
 818
 819 /**
 820  * soup_message_get_proxy_auth:
 821  * @msg: a #SoupMessage
 822  *
 823  * Gets the #SoupAuth used by @msg for authentication to its proxy..
 824  *
 825  * Return value: the #SoupAuth used by @msg for authentication to its
 826  * proxy, or %NULL if @msg isn't authenticated to its proxy.
 827  **/
 828 SoupAuth *
 829 soup_message_get_proxy_auth (SoupMessage *msg)
 830 {
 831         g_return_val_if_fail (SOUP_IS_MESSAGE (msg), NULL);
 832
 833         return SOUP_MESSAGE_GET_PRIVATE (msg)->proxy_auth;
 834 }
 835
 836 /**
 837  * soup_message_cleanup_response:
 838  * @req: a #SoupMessage
 839  *
 840  * Cleans up all response data on @req, so that the request can be sent
 841  * again and receive a new response. (Eg, as a result of a redirect or
 842  * authorization request.)
 843  **/
 844 void
 845 soup_message_cleanup_response (SoupMessage *req)
 846 {
 847         if (req->response.owner == SOUP_BUFFER_SYSTEM_OWNED)
 848                 g_free (req->response.body);
 849
 850         req->response.owner = 0;
 851         req->response.body = NULL;
 852         req->response.length = 0;
 853
 854         free_chunks (req);
 855
 856         soup_message_clear_headers (req->response_headers);
 857
 858         req->status_code = SOUP_STATUS_NONE;
 859         if (req->reason_phrase) {
 860                 g_free ((char *) req->reason_phrase);
 861                 req->reason_phrase = NULL;
 862         }
 863 }
 864
 865 /**
 866  * soup_message_set_flags:
 867  * @msg: a #SoupMessage
 868  * @flags: a set of #SoupMessageFlags values
 869  *
 870  * Sets the specified flags on @msg.
 871  **/
 872 void
 873 soup_message_set_flags (SoupMessage *msg, guint flags)
 874 {
 875         g_return_if_fail (SOUP_IS_MESSAGE (msg));
 876
 877         SOUP_MESSAGE_GET_PRIVATE (msg)->msg_flags = flags;
 878 }
 879
 880 /**
 881  * soup_message_get_flags:
 882  * @msg: a #SoupMessage
 883  *
 884  * Gets the flags on @msg
 885  *
 886  * Return value: the flags
 887  **/
 888 guint
 889 soup_message_get_flags (SoupMessage *msg)
 890 {
 891         g_return_val_if_fail (SOUP_IS_MESSAGE (msg), 0);
 892
 893         return SOUP_MESSAGE_GET_PRIVATE (msg)->msg_flags;
 894 }
 895
 896 /**
 897  * soup_message_set_http_version:
 898  * @msg: a #SoupMessage
 899  * @version: the HTTP version
 900  *
 901  * Sets the HTTP version on @msg. The default version is
 902  * %SOUP_HTTP_1_1. Setting it to %SOUP_HTTP_1_0 will prevent certain
 903  * functionality from being used.
 904  **/
 905 void
 906 soup_message_set_http_version (SoupMessage *msg, SoupHttpVersion version)
 907 {
 908         g_return_if_fail (SOUP_IS_MESSAGE (msg));
 909
 910         SOUP_MESSAGE_GET_PRIVATE (msg)->http_version = version;
 911 }
 912
 913 /**
 914  * soup_message_get_http_version:
 915  * @msg: a #SoupMessage
 916  *
 917  * Gets the HTTP version of @msg. This is the minimum of the
 918  * version from the request and the version from the response.
 919  *
 920  * Return value: the HTTP version
 921  **/
 922 SoupHttpVersion
 923 soup_message_get_http_version (SoupMessage *msg)
 924 {
 925         g_return_val_if_fail (SOUP_IS_MESSAGE (msg), SOUP_HTTP_1_0);
 926
 927         return SOUP_MESSAGE_GET_PRIVATE (msg)->http_version;
 928 }
 929
 930 /**
 931  * soup_message_is_keepalive:
 932  * @msg: a #SoupMessage
 933  *
 934  * Determines whether or not @msg's connection can be kept alive for
 935  * further requests after processing @msg.
 936  *
 937  * Return value: %TRUE or %FALSE.
 938  **/
 939 gboolean
 940 soup_message_is_keepalive (SoupMessage *msg)
 941 {
 942         const char *c_conn, *s_conn;
 943
 944         c_conn = soup_message_get_header (msg->request_headers, "Connection");
 945         s_conn = soup_message_get_header (msg->response_headers, "Connection");
 946
 947         if (msg->status_code == SOUP_STATUS_OK &&
 948             soup_method_get_id (msg->method) == SOUP_METHOD_ID_CONNECT)
 949                 return TRUE;
 950
 951         if (SOUP_MESSAGE_GET_PRIVATE (msg)->http_version == SOUP_HTTP_1_0) {
 952                 /* Only persistent if the client requested keepalive
 953                  * and the server agreed.
 954                  */
 955
 956                 if (!c_conn || !s_conn)
 957                         return FALSE;
 958                 if (g_ascii_strcasecmp (c_conn, "Keep-Alive") != 0 ||
 959                     g_ascii_strcasecmp (s_conn, "Keep-Alive") != 0)
 960                         return FALSE;
 961
 962                 return TRUE;
 963         } else {
 964                 /* Normally persistent unless either side requested otherwise */
 965                 if (c_conn && g_ascii_strcasecmp (c_conn, "close") == 0)
 966                         return FALSE;
 967                 if (s_conn && g_ascii_strcasecmp (s_conn, "close") == 0)
 968                         return FALSE;
 969
 970                 /* But not if the server sent a terminate-by-EOF response */
 971                 if (soup_message_get_response_encoding (msg, NULL) == SOUP_TRANSFER_EOF)
 972                         return FALSE;
 973
 974                 return TRUE;
 975         }
 976 }
 977
 978 /**
 979  * soup_message_set_uri:
 980  * @msg: a #SoupMessage
 981  * @uri: the new #SoupUri
 982  *
 983  * Sets @msg's URI to @uri. If @msg has already been sent and you want
 984  * to re-send it with the new URI, you need to call
 985  * soup_session_requeue_message().
 986  **/
 987 void
 988 soup_message_set_uri (SoupMessage *msg, const SoupUri *uri)
 989 {
 990         SoupMessagePrivate *priv;
 991
 992         g_return_if_fail (SOUP_IS_MESSAGE (msg));
 993         priv = SOUP_MESSAGE_GET_PRIVATE (msg);
 994
 995         if (priv->uri)
 996                 soup_uri_free (priv->uri);
 997         priv->uri = soup_uri_copy (uri);
 998 }
 999
1000 /**
1001  * soup_message_get_uri:
1002  * @msg: a #SoupMessage
1003  *
1004  * Gets @msg's URI
1005  *
1006  * Return value: the URI @msg is targeted for.
1007  **/
1008 const SoupUri *
1009 soup_message_get_uri (SoupMessage *msg)
1010 {
1011         g_return_val_if_fail (SOUP_IS_MESSAGE (msg), NULL);
1012
1013         return SOUP_MESSAGE_GET_PRIVATE (msg)->uri;
1014 }
1015
1016 /**
1017  * soup_message_get_request_encoding:
1018  * @msg: a #SoupMessage
1019  * @content_length: a pointer to store the Content-Length in (or
1020  * %NULL).
1021  *
1022  * Gets @msg's request encoding. For an outgoing (client) request,
1023  * this is only valid after the message has been fully set up (from
1024  * the library's perspective, that means not until the message has
1025  * been queued). For an incoming (server) request, this is valid after
1026  * the request headers have been read and @msg->request_headers filled
1027  * in.
1028  *
1029  * Return value: the request encoding (which cannot be
1030  * %SOUP_TRANSFER_UNKNOWN or %SOUP_TRANSFER_EOF). If it is
1031  * %SOUP_TRANSFER_CONTENT_LENGTH, *@content_length will be set to the
1032  * request body's length.
1033  **/
1034 SoupTransferEncoding
1035 soup_message_get_request_encoding  (SoupMessage *msg, guint *content_length)
1036 {
1037         if (SOUP_IS_SERVER_MESSAGE (msg)) {
1038                 const char *enc, *len;
1039
1040                 enc = soup_message_get_header (msg->request_headers,
1041                                                "Transfer-Encoding");
1042                 len = soup_message_get_header (msg->request_headers,
1043                                                "Content-Length");
1044                 if (enc) {
1045                         if (g_ascii_strcasecmp (enc, "chunked") == 0)
1046                                 return SOUP_TRANSFER_CHUNKED;
1047                         else
1048                                 return SOUP_TRANSFER_UNKNOWN;
1049                 } else if (len) {
1050                         int lval = atoi (len);
1051
1052                         if (lval < 0)
1053                                 return SOUP_TRANSFER_UNKNOWN;
1054                         else {
1055                                 if (content_length)
1056                                         *content_length = lval;
1057                                 return SOUP_TRANSFER_CONTENT_LENGTH;
1058                         }
1059                 } else
1060                         return SOUP_TRANSFER_NONE;
1061         } else {
1062                 if (msg->request.length) {
1063                         if (content_length)
1064                                 *content_length = msg->request.length;
1065                         return SOUP_TRANSFER_CONTENT_LENGTH;
1066                 } else
1067                         return SOUP_TRANSFER_NONE;
1068         }
1069 }
1070
1071 /**
1072  * soup_message_get_response_encoding:
1073  * @msg: a #SoupMessage
1074  * @content_length: a pointer to store the Content-Length in (or
1075  * %NULL).
1076  *
1077  * Gets @msg's response encoding. For an outgoing (client) request,
1078  * this is only valid after the response headers have been read and
1079  * @msg->response_headers filled in. For an incoming (server) request,
1080  * this is valid after the server handler has run.
1081  *
1082  * Note that the returned value is the encoding actually used on the
1083  * wire; this will not agree with the response headers in some cases
1084  * (eg, a HEAD response may have a Content-Length header, but will
1085  * still be considered %SOUP_TRANSFER_NONE by this function).
1086  *
1087  * Return value: the response encoding (which will not be
1088  * %SOUP_TRANSFER_UNKNOWN). If it is %SOUP_TRANSFER_CONTENT_LENGTH,
1089  * *@content_length will be set to the response body's length.
1090  **/
1091 SoupTransferEncoding
1092 soup_message_get_response_encoding (SoupMessage *msg, guint *content_length)
1093 {
1094         SoupMethodId method = soup_method_get_id (msg->method);
1095
1096         if (method == SOUP_METHOD_ID_HEAD ||
1097             msg->status_code  == SOUP_STATUS_NO_CONTENT ||
1098             msg->status_code  == SOUP_STATUS_NOT_MODIFIED ||
1099             SOUP_STATUS_IS_INFORMATIONAL (msg->status_code))
1100                 return SOUP_TRANSFER_NONE;
1101
1102         if (SOUP_IS_SERVER_MESSAGE (msg)) {
1103                 SoupTransferEncoding enc =
1104                         soup_server_message_get_encoding ((SoupServerMessage *)msg);
1105                 if (enc == SOUP_TRANSFER_UNKNOWN)
1106                         enc = SOUP_TRANSFER_CONTENT_LENGTH;
1107                 if (enc == SOUP_TRANSFER_CONTENT_LENGTH && content_length)
1108                         *content_length = msg->response.length;
1109                 return enc;
1110         } else {
1111                 const char *enc, *len;
1112
1113                 enc = soup_message_get_header (msg->response_headers,
1114                                                "Transfer-Encoding");
1115                 len = soup_message_get_header (msg->response_headers,
1116                                                "Content-Length");
1117                 if (enc) {
1118                         if (g_ascii_strcasecmp (enc, "chunked") == 0)
1119                                 return SOUP_TRANSFER_CHUNKED;
1120                         else
1121                                 return SOUP_TRANSFER_UNKNOWN;
1122                 } else if (len) {
1123                         int lval = atoi (len);
1124
1125                         if (lval < 0)
1126                                 return SOUP_TRANSFER_UNKNOWN;
1127                         else {
1128                                 if (content_length)
1129                                         *content_length = lval;
1130                                 return SOUP_TRANSFER_CONTENT_LENGTH;
1131                         }
1132                 } else if (method == SOUP_METHOD_ID_CONNECT)
1133                         return SOUP_TRANSFER_NONE;
1134                 else
1135                         return SOUP_TRANSFER_EOF;
1136         }
1137 }
1138
1139 /**
1140  * soup_message_set_status:
1141  * @msg: a #SoupMessage
1142  * @status_code: an HTTP status code
1143  *
1144  * Sets @msg's status code to @status_code. If @status_code is a
1145  * known value, it will also set @msg's reason_phrase.
1146  **/
1147 void
1148 soup_message_set_status (SoupMessage *msg, guint status_code)
1149 {
1150         g_return_if_fail (SOUP_IS_MESSAGE (msg));
1151         g_return_if_fail (status_code != 0);
1152
1153         g_free ((char *) msg->reason_phrase);
1154
1155         msg->status_code = status_code;
1156         msg->reason_phrase = g_strdup (soup_status_get_phrase (status_code));
1157 }
1158
1159 /**
1160  * soup_message_set_status_full:
1161  * @msg: a #SoupMessage
1162  * @status_code: an HTTP status code
1163  * @reason_phrase: a description of the status
1164  *
1165  * Sets @msg's status code and reason phrase.
1166  **/
1167 void
1168 soup_message_set_status_full (SoupMessage *msg,
1169                               guint        status_code,
1170                               const char  *reason_phrase)
1171 {
1172         g_return_if_fail (SOUP_IS_MESSAGE (msg));
1173         g_return_if_fail (status_code != 0);
1174         g_return_if_fail (reason_phrase != NULL);
1175
1176         g_free ((char *) msg->reason_phrase);
1177
1178         msg->status_code = status_code;
1179         msg->reason_phrase = g_strdup (reason_phrase);
1180 }
1181
1182
1183 /**
1184  * soup_message_add_chunk:
1185  * @msg: a #SoupMessage
1186  * @owner: the ownership of @body
1187  * @body: body data
1188  * @length: length of @body
1189  *
1190  * Adds a chunk of response data to @body. (Note that currently
1191  * there is no way to send a request using chunked encoding.)
1192  **/
1193 void
1194 soup_message_add_chunk (SoupMessage   *msg,
1195                         SoupOwnership  owner,
1196                         const char    *body,
1197                         guint          length)
1198 {
1199         SoupMessagePrivate *priv;
1200         SoupDataBuffer *chunk;
1201
1202         g_return_if_fail (SOUP_IS_MESSAGE (msg));
1203         priv = SOUP_MESSAGE_GET_PRIVATE (msg);
1204         g_return_if_fail (body != NULL || length == 0);
1205
1206         chunk = g_new0 (SoupDataBuffer, 1);
1207         if (owner == SOUP_BUFFER_USER_OWNED) {
1208                 chunk->owner = SOUP_BUFFER_SYSTEM_OWNED;
1209                 chunk->body = g_memdup (body, length);
1210         } else {
1211                 chunk->owner = owner;
1212                 chunk->body = (char *)body;
1213         }
1214         chunk->length = length;
1215
1216         if (priv->chunks) {
1217                 priv->last_chunk = g_slist_append (priv->last_chunk, chunk);
1218                 priv->last_chunk = priv->last_chunk->next;
1219         } else {
1220                 priv->chunks = priv->last_chunk =
1221                         g_slist_append (NULL, chunk);
1222         }
1223 }
1224
1225 /**
1226  * soup_message_add_final_chunk:
1227  * @msg: a #SoupMessage
1228  *
1229  * Adds a final, empty chunk of response data to @body. This must
1230  * be called after adding the last real chunk, to indicate that
1231  * there is no more data.
1232  **/
1233 void
1234 soup_message_add_final_chunk (SoupMessage *msg)
1235 {
1236         soup_message_add_chunk (msg, SOUP_BUFFER_STATIC, NULL, 0);
1237 }
1238
1239 /**
1240  * soup_message_pop_chunk:
1241  * @msg: a #SoupMessage
1242  *
1243  * Pops a chunk of response data from @msg's chunk list. The caller
1244  * must free @chunk itself, and must handle the data in @chunk
1245  * according to its %ownership.
1246  *
1247  * Return value: the chunk, or %NULL if there are no chunks left.
1248  **/
1249 SoupDataBuffer *
1250 soup_message_pop_chunk (SoupMessage *msg)
1251 {
1252         SoupMessagePrivate *priv;
1253         SoupDataBuffer *chunk;
1254
1255         g_return_val_if_fail (SOUP_IS_MESSAGE (msg), NULL);
1256         priv = SOUP_MESSAGE_GET_PRIVATE (msg);
1257
1258         if (!priv->chunks)
1259                 return NULL;
1260
1261         chunk = priv->chunks->data;
1262         priv->chunks = g_slist_remove (priv->chunks, chunk);
1263         if (!priv->chunks)
1264                 priv->last_chunk = NULL;
1265
1266         return chunk;
1267 }
1268
1269 static void
1270 free_chunks (SoupMessage *msg)
1271 {
1272         SoupMessagePrivate *priv = SOUP_MESSAGE_GET_PRIVATE (msg);
1273         SoupDataBuffer *chunk;
1274         GSList *ch;
1275
1276         for (ch = priv->chunks; ch; ch = ch->next) {
1277                 chunk = ch->data;
1278
1279                 if (chunk->owner == SOUP_BUFFER_SYSTEM_OWNED)
1280                         g_free (chunk->body);
1281                 g_free (chunk);
1282         }
1283
1284         g_slist_free (priv->chunks);
1285         priv->chunks = priv->last_chunk = NULL;
1286 }