* libsoup/soup-error.c: Fix a spelling mistake.
* libsoup/*.c: Fix use of @/%/#/() in gtk-doc comments
+2003-08-14 Dan Winship <danw@ximian.com>
+
+ * libsoup/soup-error.c: Fix a spelling mistake.
+
+ * libsoup/*.c: Fix use of @/%/#/() in gtk-doc comments
+
2003-08-12 Dan Winship <danw@ximian.com>
* libsoup/soup-auth.c: Make this an abstract GObject. Tweak some
* soup_context_get:
* @uri: the stringified URI.
*
- * Returns a pointer to the %SoupContext representing @uri. If a context
- * already exists for the URI, it is returned with an added reference.
- * Otherwise, a new context is created with a reference count of one.
+ * Returns a pointer to the #SoupContext representing @uri. If a
+ * context already exists for the URI, it is returned with an added
+ * reference. Otherwise, a new context is created with a reference
+ * count of one.
*
- * Return value: a %SoupContext representing @uri.
+ * Return value: a #SoupContext representing @uri.
*/
SoupContext *
soup_context_get (const gchar *uri)
/**
* soup_context_uri_hash:
- * @key: a %SoupUri
+ * @key: a #SoupUri
*
- * Return value: Hash value of the user, authmech, passwd, and path fields in
- * @key.
+ * Return value: Hash value of the user, passwd, path, and query
+ * fields in @key.
**/
static guint
soup_context_uri_hash (gconstpointer key)
/**
* soup_context_uri_equal:
- * @v1: a %SoupUri
- * @v2: a %SoupUri
+ * @v1: a #SoupUri
+ * @v2: a #SoupUri
*
- * Return value: TRUE if @v1 and @v2 match in user, authmech, passwd, and
- * path. Otherwise, FALSE.
+ * Return value: %TRUE if @v1 and @v2 match in user, passwd, path, and
+ * query. Otherwise, %FALSE.
**/
static gboolean
soup_context_uri_equal (gconstpointer v1, gconstpointer v2)
/**
* soup_context_from_uri:
- * @suri: a %SoupUri.
+ * @suri: a #SoupUri.
*
- * Returns a pointer to the %SoupContext representing @suri. If a context
- * already exists for the URI, it is returned with an added reference.
- * Otherwise, a new context is created with a reference count of one.
+ * Returns a pointer to the #SoupContext representing @suri. If a
+ * context already exists for the URI, it is returned with an added
+ * reference. Otherwise, a new context is created with a reference
+ * count of one.
*
- * Return value: a %SoupContext representing @uri.
+ * Return value: a #SoupContext representing @uri.
*/
SoupContext *
soup_context_from_uri (SoupUri *suri)
/**
* soup_context_ref:
- * @ctx: a %SoupContext.
+ * @ctx: a #SoupContext.
*
* Adds a reference to @ctx.
*/
/**
* soup_context_unref:
- * @ctx: a %SoupContext.
+ * @ctx: a #SoupContext.
*
- * Decrement the reference count on @ctx. If the reference count reaches
- * zero, the %SoupContext is freed. If this is the last context for a
- * given server address, any open connections are closed.
+ * Decrement the reference count on @ctx. If the reference count
+ * reaches zero, the #SoupContext is freed. If this is the last
+ * context for a given server address, any open connections are
+ * closed.
*/
void
soup_context_unref (SoupContext *ctx)
/**
* soup_context_get_connection:
- * @ctx: a %SoupContext.
- * @cb: a %SoupConnectCallbackFn to be called when a valid connection is
+ * @ctx: a #SoupContext.
+ * @cb: a #SoupConnectCallbackFn to be called when a valid connection is
* available.
* @user_data: the user_data passed to @cb.
*
* Initiates the process of establishing a network connection to the
- * server referenced in @ctx. If an existing connection is available and
- * not in use, @cb is called immediately, and a %SoupConnectId of 0 is
- * returned. Otherwise, a new connection is established. If the current
- * connection count exceeds that set in @soup_set_connection_limit, the
- * new connection is not created until an existing connection is closed.
+ * server referenced in @ctx. If an existing connection is available
+ * and not in use, @cb is called immediately, and a #SoupConnectId of
+ * 0 is returned. Otherwise, a new connection is established. If the
+ * current connection count exceeds that set in
+ * soup_set_connection_limit(), the new connection is not created
+ * until an existing connection is closed.
*
- * Once a network connection is successfully established, or an existing
- * connection becomes available for use, @cb is called, passing the
- * %SoupConnection representing it.
+ * Once a network connection is successfully established, or an
+ * existing connection becomes available for use, @cb is called,
+ * passing the #SoupConnection representing it.
*
- * Return value: a %SoupConnectId which can be used to cancel a connection
- * attempt using %soup_context_cancel_connect.
+ * Return value: a #SoupConnectId which can be used to cancel a
+ * connection attempt using soup_context_cancel_connect().
*/
SoupConnectId
soup_context_get_connection (SoupContext *ctx,
/**
* soup_context_cancel_connect:
- * @tag: a %SoupConnextId representing a connection in progress.
+ * @tag: a #SoupConnectId representing a connection in progress.
*
* Cancels the connection attempt represented by @tag. The
- * %SoupConnectCallbackFn passed in %soup_context_get_connection is not
- * called.
+ * #SoupConnectCallbackFn passed in soup_context_get_connection() is
+ * not called.
*/
void
soup_context_cancel_connect (SoupConnectId tag)
/**
* soup_context_get_uri:
- * @ctx: a %SoupContext.
+ * @ctx: a #SoupContext.
*
- * Returns a pointer to the %SoupUri represented by @ctx.
+ * Returns a pointer to the #SoupUri represented by @ctx.
*
- * Return value: the %SoupUri for @ctx.
+ * Return value: the #SoupUri for @ctx.
*/
const SoupUri *
soup_context_get_uri (SoupContext *ctx)
/**
* soup_connection_release:
- * @conn: a %SoupConnection currently in use.
+ * @conn: a #SoupConnection currently in use.
*
* Mark the connection represented by @conn as being unused. If the
- * keep-alive flag is not set on the connection, the connection is closed
- * and its resources freed, otherwise the connection is returned to the
- * unused connection pool for the server.
+ * keep-alive flag is not set on the connection, the connection is
+ * closed and its resources freed, otherwise the connection is
+ * returned to the unused connection pool for the server.
*/
void
soup_connection_release (SoupConnection *conn)
/**
* soup_connection_get_iochannel:
- * @conn: a %SoupConnection.
+ * @conn: a #SoupConnection.
*
- * Returns a GIOChannel used for IO operations on the network connection
- * represented by @conn.
+ * Returns a #GIOChannel used for IO operations on the network
+ * connection represented by @conn.
*
- * Return value: a pointer to the GIOChannel used for IO on %conn.
+ * Return value: a pointer to the #GIOChannel used for IO on @conn.
*/
GIOChannel *
soup_connection_get_iochannel (SoupConnection *conn)
/**
* soup_connection_set_keep_alive:
- * @conn: a %SoupConnection.
+ * @conn: a #SoupConnection.
* @keep_alive: boolean keep-alive value.
*
- * Sets the keep-alive flag on the %SoupConnection pointed to by %conn.
+ * Sets the keep-alive flag on the #SoupConnection pointed to by
+ * @conn.
*/
void
soup_connection_set_keep_alive (SoupConnection *conn, gboolean keep_alive)
/**
* soup_connection_is_keep_alive:
- * @conn: a %SoupConnection.
+ * @conn: a #SoupConnection.
*
- * Returns the keep-alive flag for the %SoupConnection pointed to by
- * %conn. If this flag is TRUE, the connection will be returned to the pool
- * of unused connections when next %soup_connection_release is called,
- * otherwise the connection will be closed and resources freed.
+ * Returns the keep-alive flag for the #SoupConnection pointed to by
+ * @conn. If this flag is TRUE, the connection will be returned to the
+ * pool of unused connections when next soup_connection_release() is
+ * called, otherwise the connection will be closed and resources
+ * freed.
*
* Return value: the keep-alive flag for @conn.
*/
/**
* soup_connection_get_context:
- * @conn: a %SoupConnection.
+ * @conn: a #SoupConnection.
*
- * Returns the %SoupContext from which @conn was created, with an added ref.
+ * Returns the #SoupContext from which @conn was created, with an
+ * added ref.
*
- * Return value: the %SoupContext associated with @conn. Unref when finished.
+ * Return value: the #SoupContext associated with @conn. Unref when
+ * finished.
*/
SoupContext *
soup_connection_get_context (SoupConnection *conn)
/**
* soup_connection_set_used:
- * @conn: a %SoupConnection.
+ * @conn: a #SoupConnection.
*
* Clears the "new" flag on @conn.
*/
/**
* soup_connection_is_new:
- * @conn: a %SoupConnection.
+ * @conn: a #SoupConnection.
*
- * Returns TRUE if this is the first use of @conn
- * (I.E. no response has been read from it yet)
+ * Returns %TRUE if this is the first use of @conn (ie. no response
+ * has been read from it yet)
*
* Return value: boolean representing whether this is the first time a
* connection has been used.
{ SOUP_ERROR_CANT_CONNECT, "Cannot connect to destination" },
{ SOUP_ERROR_CANT_CONNECT_PROXY, "Cannot connect to proxy" },
{ SOUP_ERROR_IO, "Connection terminated "
- "unexpectadly" },
+ "unexpectedly" },
{ SOUP_ERROR_MALFORMED, "Message Corrupt" },
{ SOUP_ERROR_CANT_AUTHENTICATE, "Authentication Failed" },
{ SOUP_ERROR_CANT_AUTHENTICATE_PROXY, "Proxy Authentication Failed" },
/**
* soup_message_new:
- * @context: a %SoupContext for the destination endpoint.
- * @method: a string which will be used as the HTTP method for the created
- * request, if NULL a GET request will be made.
+ * @context: a #SoupContext for the destination endpoint.
+ * @method: a string which will be used as the HTTP method for the
+ * created request
*
- * Creates a new empty %SoupMessage, which will connect to the URL represented
- * by @context. A reference will be added to @context.
+ * Creates a new empty #SoupMessage, which will connect to the URL
+ * represented by @context. A reference will be added to @context.
*
- * The new message has a status of @SOUP_STATUS_IDLE.
+ * The new message has a status of %SOUP_STATUS_IDLE.
*
- * Return value: the new %SoupMessage.
+ * Return value: the new #SoupMessage.
*/
SoupMessage *
soup_message_new (SoupContext *context, const gchar *method)
/**
* soup_message_new_full:
- * @context: a %SoupContext for the destination endpoint.
- * @method: a string which will be used as the HTTP method for the created
- * request, if NULL a GET request will be made..
- * @req_owner: the %SoupOwnership of the passed data buffer.
+ * @context: a #SoupContext for the destination endpoint.
+ * @method: a string which will be used as the HTTP method for the
+ * created request.
+ * @req_owner: the #SoupOwnership of the passed data buffer.
* @req_body: a data buffer containing the body of the message request.
* @req_length: the byte length of @req_body.
*
- * Creates a new %SoupMessage, which will connect to the URL represented by
- * @context. A reference is added to @context. The request data
- * buffer will be filled from @req_owner, @req_body, and @req_length
- * respectively.
+ * Creates a new #SoupMessage, which will connect to the URL
+ * represented by @context. A reference is added to @context. The
+ * request data buffer will be filled from @req_owner, @req_body, and
+ * @req_length.
*
- * The new message has a status of @SOUP_STATUS_IDLE.
+ * The new message has a status of %SOUP_STATUS_IDLE.
*
- * Return value: the new %SoupMessage.
+ * Return value: the new #SoupMessage.
*/
SoupMessage *
soup_message_new_full (SoupContext *context,
/**
* soup_message_cleanup:
- * @req: a %SoupMessage.
+ * @req: a #SoupMessage.
*
- * Frees any temporary resources created in the processing of @req. Also
- * releases the active connection, if one exists. Request and response data
- * buffers are left intact.
+ * Frees any temporary resources created in the processing of @req.
+ * Also releases the active connection, if one exists. Request and
+ * response data buffers are left intact.
*/
void
soup_message_cleanup (SoupMessage *req)
/**
* soup_message_free:
- * @req: a %SoupMessage to destroy.
+ * @req: a #SoupMessage to destroy.
*
- * Destroys the %SoupMessage pointed to by @req. Request and response headers
- * are freed. Request and response data buffers are also freed if their
- * ownership is %SOUP_BUFFER_SYSTEM_OWNED. The message's destination context
- * will be de-referenced.
+ * Destroys the #SoupMessage pointed to by @req. Request and response
+ * headers are freed. Request and response data buffers are also freed
+ * if their ownership is %SOUP_BUFFER_SYSTEM_OWNED. The message's
+ * destination context will be unreferenced.
*/
void
soup_message_free (SoupMessage *req)
/**
* soup_message_issue_callback:
- * @req: a %SoupMessage currently being processed.
- * @error: a %SoupErrorCode to be passed to %req's completion callback.
+ * @req: a #SoupMessage currently being processed.
+ * @error: a #SoupErrorCode to be passed to @req's completion callback.
*
- * Finalizes the message request, by first freeing any temporary resources, then
- * issuing the callback function pointer passed in %soup_message_new or
- * %soup_message_new_full. If, after returning from the callback, the message
- * has not been requeued, @msg is destroyed using %soup_message_free.
+ * Finalizes the message request, by first freeing any temporary
+ * resources, then issuing the callback function pointer passed in
+ * soup_message_new() or soup_message_new_full(). If, after returning
+ * from the callback, the message has not been requeued, @msg is
+ * destroyed using soup_message_free().
*/
void
soup_message_issue_callback (SoupMessage *req)
/**
* soup_message_cancel:
- * @req: a %SoupMessage currently being processed.
+ * @req: a #SoupMessage currently being processed.
*
* Cancel a running message, and issue completion callback with a
- * %SoupTransferStatus of %SOUP_ERROR_CANCELLED. If not requeued by the
- * completion callback, the @msg will be destroyed.
+ * #SoupTransferStatus of %SOUP_ERROR_CANCELLED. If not requeued by
+ * the completion callback, the @msg will be destroyed.
*/
void
soup_message_cancel (SoupMessage *msg)
/**
* soup_message_get_header:
- * @req: a %SoupMessage.
+ * @req: a #SoupMessage.
* @name: header name.
*
* Lookup the first transport header with a key equal to @name.
*
- * Return value: the header's value or NULL if not found.
+ * Return value: the header's value or %NULL if not found.
*/
const gchar *
soup_message_get_header (GHashTable *hash,
/**
* soup_message_get_header_list:
- * @req: a %SoupMessage.
+ * @req: a #SoupMessage.
* @name: header name.
*
* Lookup the all transport request headers with a key equal to @name.
*
- * Return value: a const pointer to a GSList of header values or NULL if not
- * found.
+ * Return value: a const pointer to a #GSList of header values or
+ * %NULL if not found.
*/
const GSList *
soup_message_get_header_list (GHashTable *hash,
/**
* soup_message_queue:
- * @req: a %SoupMessage.
- * @callback: a %SoupCallbackFn which will be called after the message completes
- * or when an unrecoverable error occurs.
+ * @req: a #SoupMessage.
+ * @callback: a #SoupCallbackFn which will be called after the message
+ * completes or when an unrecoverable error occurs.
* @user_data: a pointer passed to @callback.
*
- * Queues the message @req for sending. All messages are processed while the
- * glib main loop runs. If this %SoupMessage has been processed before, any
- * resources related to the time it was last sent are freed.
+ * Queues the message @req for sending. All messages are processed
+ * while the glib main loop runs. If this #SoupMessage has been
+ * processed before, any resources related to the time it was last
+ * sent are freed.
*
- * If the response %SoupDataBuffer has an owner of %SOUP_BUFFER_USER_OWNED, the
- * message will not be queued, and @callback will be called with a
- * %SoupErrorCode of %SOUP_ERROR_CANCELLED.
+ * If the response #SoupDataBuffer has an owner of
+ * %SOUP_BUFFER_USER_OWNED, the message will not be queued, and
+ * @callback will be called with a #SoupErrorCode of
+ * %SOUP_ERROR_CANCELLED.
*
- * Upon message completetion, the callback specified in @callback will be
- * invoked. If after returning from this callback the message has not been
- * requeued using %soup_message_queue, %soup_message_free will be called on
- * @req.
+ * Upon message completetion, the callback specified in @callback will
+ * be invoked. If after returning from this callback the message has
+ * not been requeued using soup_message_queue(), soup_message_free()
+ * will be called on @req.
*/
void
soup_message_queue (SoupMessage *req,
/**
* soup_message_requeue:
- * @req: a %SoupMessage
+ * @req: a #SoupMessage
*
- * This causes @req to be placed back on the queue to be attempted again.
+ * This causes @req to be placed back on the queue to be attempted
+ * again.
**/
void
soup_message_requeue (SoupMessage *req)
/**
* soup_message_send:
- * @msg: a %SoupMessage.
+ * @msg: a #SoupMessage.
*
- * Syncronously send @msg. This call will not return until the transfer is
- * finished successfully or there is an unrecoverable error.
+ * Synchronously send @msg. This call will not return until the
+ * transfer is finished successfully or there is an unrecoverable
+ * error.
*
- * @msg is not free'd upon return.
+ * @msg is not freed upon return.
*
- * Return value: the %SoupErrorClass of the error encountered while sending or
- * reading the response.
+ * Return value: the #SoupErrorClass of the error encountered while
+ * sending or reading the response.
*/
SoupErrorClass
soup_message_send (SoupMessage *msg)
/**
* soup_queue_shutdown:
*
- * Shut down the message queue by calling %soup_message_cancel on all active
- * requests and then closing all open connections.
+ * Shut down the message queue by calling soup_message_cancel() on all
+ * active requests and then closing all open connections.
*/
void
soup_queue_shutdown (void)
* connects to the specified address and port and then calls the
* callback with the data. Use this function when you're a client
* connecting to a server and you don't want to block or mess with
- * #SoupAddress's. It may call the callback before the function
+ * #SoupAddress. It may call the callback before the function
* returns. It will call the callback if there is a failure.
*
* Returns: ID of the connection which can be used with
- * soup_socket_connect_cancel() to cancel it; NULL if it succeeds
- * or fails immediately.
+ * soup_socket_connect_cancel() to cancel it; %NULL if it succeeds or
+ * fails immediately.
**/
SoupSocketConnectId
soup_socket_connect (const char *hostname,
/**
* soup_socket_get_iochannel:
- * @socket: SoupSocket to get GIOChannel from.
+ * @socket: #SoupSocket to get #GIOChannel from.
*
* Get the #GIOChannel for the #SoupSocket.
*
* you are done with it. However, you should not close the channel -
* this is done when you delete the socket.
*
- * Returns: A #GIOChannel; NULL on failure.
+ * Returns: A #GIOChannel; %NULL on failure.
*
**/
GIOChannel*
* address of that machine. If it is a listening socket, the address
* will be %NULL.
*
- * Returns: #SoupAddress of socket; NULL on failure.
+ * Returns: #SoupAddress of socket; %NULL on failure.
**/
SoupAddress *
soup_socket_get_address (const SoupSocket *socket)
/**
* soup_socket_get_port:
- * @socket: SoupSocket to get the port number of.
+ * @socket: #SoupSocket to get the port number of.
*
* Get the port number the socket is bound to.
*
* soup_socket_server_new:
* @local_addr: Local address to bind to. (soup_address_ipv4_any() to
* accept connections on any local IPv4 address)
- * @local_port: Port number for the socket (SOUP_SERVER_ANY_PORT if you
+ * @local_port: Port number for the socket (%SOUP_SERVER_ANY_PORT if you
* don't care).
*
* Create and open a new #SoupSocket listening on the specified
* and you know what the port number should be (or pass 0 if you don't
* care what the port is).
*
- * Returns: a new #SoupSocket, or NULL if there was a failure.
+ * Returns: a new #SoupSocket, or %NULL if there was a failure.
**/
SoupSocket *
soup_socket_server_new (SoupAddress *local_addr, guint local_port)
* the callback if there is a failure.
*
* Returns: ID of the connection which can be used with
- * soup_socket_connect_cancel() to cancel it; NULL on
+ * soup_socket_connect_cancel() to cancel it; %NULL on
* failure.
**/
SoupSocketNewId
* want to block). If the socket's #GIOChannel is readable, it DOES
* NOT mean that this function will not block.
*
- * Returns: a new #SoupSocket if there is another connect, or NULL if
+ * Returns: a new #SoupSocket if there is another connect, or %NULL if
* there's an error.
**/
SoupSocket *
* function is best used with the sockets #GIOChannel. If the
* channel is readable, then you PROBABLY have a connection. It is
* possible for the connection to close by the time you call this, so
- * it may return NULL even if the channel was readable.
+ * it may return %NULL even if the channel was readable.
*
- * Returns a new SoupSocket if there is another connect, or NULL
+ * Returns a new SoupSocket if there is another connect, or %NULL
* otherwise.
**/
SoupSocket *
*
* Parses @uri_string relative to @base.
*
- * Return value: a parsed SoupUri.
+ * Return value: a parsed #SoupUri.
**/
SoupUri *
soup_uri_new_with_base (const SoupUri *base, const char *uri_string)
*
* Parses an absolute URI.
*
- * Return value: a SoupUri, or %NULL.
+ * Return value: a #SoupUri, or %NULL.
**/
SoupUri *
soup_uri_new (const char *uri_string)
/**
* soup_uri_to_string:
- * @uri: a SoupUri
+ * @uri: a #SoupUri
* @just_path: if %TRUE, output just the path and query portions
*
* Return value: a string representing @uri, which the caller must free.
projects / platform / upstream / libsoup.git / commitdiff