libsoup r1248 - in trunk: . libsoup

[danw svn gnome org]

Author: danw
Date: Wed Mar 11 17:51:43 2009
New Revision: 1248
URL: http://svn.gnome.org/viewvc/libsoup?rev=1248&view=rev

Log:
	* libsoup/soup-session.c (soup_session_cancel_message): add more
	detail to the doc comment

	* libsoup/soup-message.c (SoupMessage): Note in the doc comment
	that reason phrases are not very useful, and should not be
	presented to the user.

	* libsoup/soup-status.c: add a comment explaining why reason
	phrases aren't localized. Also some misc doc fixes.
	(soup_status_get_phrase): Note in the doc comment that you
	shouldn't present reason phrases to the user.


Modified:
   trunk/ChangeLog
   trunk/libsoup/soup-message.c
   trunk/libsoup/soup-session.c
   trunk/libsoup/soup-status.c

Modified: trunk/libsoup/soup-message.c
==============================================================================
--- trunk/libsoup/soup-message.c	(original)
+++ trunk/libsoup/soup-message.c	Wed Mar 11 17:51:43 2009
@@ -52,6 +52,17 @@
  *
  * Represents an HTTP message being sent or received.
  *
+ * @status_code will normally be a #SoupKnownStatusCode, eg,
+ * %SOUP_STATUS_OK, though of course it might actually be an unknown
+ * status code. @reason_phrase is the actual text returned from the
+ * server, which may or may not correspond to the "standard"
+ * description of @status_code. At any rate, it is almost certainly
+ * not localized, and not very descriptive even if it is in the user's
+ * language; you should not use @reason_phrase in user-visible
+ * messages. Rather, you should look at @status_code, and determine an
+ * end-user-appropriate message based on that and on what you were
+ * trying to do.
+ *
  * As described in the #SoupMessageBody documentation, the
  * @request_body and @response_body %data fields will not necessarily
  * be filled in at all times. When they are filled in, they will be

Modified: trunk/libsoup/soup-session.c
==============================================================================
--- trunk/libsoup/soup-session.c	(original)
+++ trunk/libsoup/soup-session.c	Wed Mar 11 17:51:43 2009
@@ -1390,9 +1390,24 @@
  * @status_code: status code to set on @msg (generally
  * %SOUP_STATUS_CANCELLED)
  *
- * Causes @session to immediately finish processing @msg, with a final
- * status_code of @status_code. Depending on when you cancel it, the
- * response state may be incomplete or inconsistent.
+ * Causes @session to immediately finish processing @msg (regardless
+ * of its current state) with a final status_code of @status_code. You
+ * may call this at any time after handing @msg off to @session; if
+ * @session has started sending the request but has not yet received
+ * the complete response, then it will close the request's connection.
+ * Note that with non-idempotent requests (eg, %POST, %PUT, %DELETE)
+ * it is possible that you might cancel the request after the server
+ * acts on it, but before it returns a response, leaving the remote
+ * resource in an unknown state.
+ *
+ * If the message is cancelled while its response body is being read,
+ * then the response body in @msg will be left partially-filled-in.
+ * The response headers, on the other hand, will always be either
+ * empty or complete.
+ *
+ * For messages queued with soup_session_queue_message() (and
+ * cancelled from the same thread), the callback will be invoked
+ * before soup_session_cancel_message() returns.
  **/
 void
 soup_session_cancel_message (SoupSession *session, SoupMessage *msg,

Modified: trunk/libsoup/soup-status.c
==============================================================================
--- trunk/libsoup/soup-status.c	(original)
+++ trunk/libsoup/soup-status.c	Wed Mar 11 17:51:43 2009
@@ -77,8 +77,7 @@
  * @SOUP_STATUS_IO_ERROR: A network error occurred, or the other end
  * closed the connection unexpectedly
  * @SOUP_STATUS_MALFORMED: Malformed data (usually a programmer error)
- * @SOUP_STATUS_TRY_AGAIN: Try again. (Only returned in certain
- * specifically documented cases)
+ * @SOUP_STATUS_TRY_AGAIN: Formerly used internally. Now unused.
  * @SOUP_STATUS_CONTINUE: 100 Continue (HTTP)
  * @SOUP_STATUS_SWITCHING_PROTOCOLS: 101 Switching Protocols (HTTP)
  * @SOUP_STATUS_PROCESSING: 102 Processing (WebDAV)
@@ -156,6 +155,19 @@
  * value.
  **/
 
+
+/* The reason_phrases are not localized because:
+ *
+ * 1. Only ASCII can be used portably in the HTTP Status-Line, so we
+ *    would not be able to return localized reason phrases from
+ *    SoupServer anyway.
+ *
+ * 2. Having a way for clients to get a localized version of a status
+ *    code would just encourage them to present those strings to the
+ *    user, which is bad because many of them are fairly
+ *    incomprehensible anyway.
+ */
+
 static const struct {
 	guint code;
 	const char *phrase;
@@ -169,7 +181,6 @@
 	{ SOUP_STATUS_SSL_FAILED,                 "SSL handshake failed" },
 	{ SOUP_STATUS_IO_ERROR,                   "Connection terminated unexpectedly" },
 	{ SOUP_STATUS_MALFORMED,                  "Message Corrupt" },
-	/* SOUP_STATUS_TRY_AGAIN should never be returned to the caller */
 
 	/* Informational */
 	{ SOUP_STATUS_CONTINUE,                   "Continue" },
@@ -235,13 +246,21 @@
  * soup_status_get_phrase:
  * @status_code: an HTTP status code
  *
- * Looks up the stock HTTP description of @status_code.
- *
- * You should not need to use this; if you are interested in the
- * textual description for the %status_code of a given #SoupMessage,
- * just look at the message's %reason_phrase.
+ * Looks up the stock HTTP description of @status_code. This is used
+ * by soup_message_set_status() to get the correct text to go with a
+ * given status code.
+ *
+ * <emphasis>There is no reason for you to ever use this
+ * function.</emphasis> If you wanted the textual description for the
+ * %status_code of a given #SoupMessage, you should just look at the
+ * message's %reason_phrase. However, you should only do that for use
+ * in debugging messages; HTTP reason phrases are not localized, and
+ * are not generally very descriptive anyway, and so they should never
+ * be presented to the user directly. Instead, you should create you
+ * own error messages based on the status code, and on what you were
+ * trying to do.
  *
- * Return value: the (English) description of @status_code
+ * Return value: the (terse, English) description of @status_code
  **/
 const char *
 soup_status_get_phrase (guint status_code)
@@ -260,9 +279,10 @@
  * soup_status_proxify:
  * @status_code: a status code
  *
- * Turns SOUP_STATUS_CANT_RESOLVE into SOUP_STATUS_CANT_RESOLVE_PROXY
- * and SOUP_STATUS_CANT_CONNECT into SOUP_STATUS_CANT_CONNECT_PROXY.
- * Other status codes are passed through unchanged.
+ * Turns %SOUP_STATUS_CANT_RESOLVE into
+ * %SOUP_STATUS_CANT_RESOLVE_PROXY and %SOUP_STATUS_CANT_CONNECT into
+ * %SOUP_STATUS_CANT_CONNECT_PROXY. Other status codes are passed
+ * through unchanged.
  *
  * Return value: the "proxified" equivalent of @status_code.
  *