Changeset 0aaca60


Ignore:
Timestamp:
2006-07-19T16:52:38Z (18 years ago)
Author:
Wilmer van der Gaast <wilmer@…>
Branches:
master
Children:
d3a672c
Parents:
04026d4
Message:

Added some (more) comments to .h files in lib/ and some minor fixes/cleanups.

Files:
6 edited

Legend:

Unmodified
Added
Removed

  • doc/user-guide/commands.xml

    r04026d4 r0aaca60  
    746746                                This command allows to set the friendly name of an im account. If no new name is specified the command will report the current name. When the name contains spaces, don't forget to quote the whole nick in double quotes. Currently this command is only supported by the MSN protocol.
    747747                        </para>
     748
     749                        <para>
     750                                It is recommended to use the per-account <emphasis>display_name</emphasis> setting to read and change this information. The <emphasis>nick</emphasis> command is deprecated.
     751                        </para>
    748752                </description>
    749753

  • irc.c

    r04026d4 r0aaca60  
    652652        {
    653653                GList *l;
    654                 char *ops = set_getstr( &irc->set, "ops" );
    655654               
    656655                /* root and the user aren't in the channel userlist but should

  • lib/events.h

    r04026d4 r0aaca60  
    2020 */
    2121
    22 /*
    23  * Split off the event handling things from proxy.[ch] (and adding timer
    24  * stuff. This to allow BitlBee to use other libs than GLib for event
    25  * handling.
    26  */
     22/* This stuff used to be in proxy.c too, but I split it off so BitlBee can
     23   use other libraries (like libevent) to handle events. proxy.c is one very
     24   nice piece of work from Gaim. It connects to a TCP server in the back-
     25   ground and calls a callback function once the connection is ready to use.
     26   This function (proxy_connect()) can be found in proxy.c. (It also
     27   transparently handles HTTP/SOCKS proxies, when necessary.)
     28   
     29   This file offers some extra event handling toys, which will be handled
     30   by GLib or libevent. The advantage of using libevent is that it can use
     31   more advanced I/O polling functions like epoll() in recent Linux
     32   kernels. This should improve BitlBee's scalability. */
    2733
    2834
    … …  
    3945#include <gmodule.h>
    4046
     47/* The conditions you can pass to gaim_input_add()/that will be passed to
     48   the given callback function. */
    4149typedef enum {
    4250        GAIM_INPUT_READ = 1 << 1,
    … …  
    4553typedef gboolean (*b_event_handler)(gpointer data, gint fd, b_input_condition cond);
    4654
     55/* For internal use. */
    4756#define GAIM_READ_COND  (G_IO_IN | G_IO_HUP | G_IO_ERR)
    4857#define GAIM_WRITE_COND (G_IO_OUT | G_IO_HUP | G_IO_ERR | G_IO_NVAL)
    … …  
    5261#define event_debug( x... )
    5362
     63/* Call this once when the program starts. It'll initialize the event handler
     64   library (if necessary) and then return immediately. */
    5465G_MODULE_EXPORT void b_main_init();
     66
     67/* This one enters the event loop. It shouldn't return until one of the event
     68   handlers calls b_main_quit(). */
    5569G_MODULE_EXPORT void b_main_run();
    5670G_MODULE_EXPORT void b_main_quit();
    5771
     72
     73/* Add event handlers (for I/O or a timeout). The event handler will be called
     74   every time the event "happens", until your event handler returns FALSE (or
     75   until you remove it using b_event_remove(). As usual, the data argument
     76   can be used to pass your own data to the event handler. */
    5877G_MODULE_EXPORT gint b_input_add(int fd, b_input_condition cond, b_event_handler func, gpointer data);
    5978G_MODULE_EXPORT gint b_timeout_add(gint timeout, b_event_handler func, gpointer data);
    6079G_MODULE_EXPORT void b_event_remove(gint id);
    6180
     81/* For now, closesocket() is only a function when using libevent. With GLib
     82   it's a preprocessor macro. */
    6283#ifdef EVENTS_LIBEVENT
    6384G_MODULE_EXPORT void closesocket(int fd);

  • lib/http_client.h

    r04026d4 r0aaca60  
    2424*/
    2525
     26/* http_client allows you to talk (asynchronously, again) to HTTP servers.
     27   In the "background" it will send the whole query and wait for a complete
     28   response to come back. Right now it's only used by the MSN Passport
     29   authentication code, but it might be useful for other things too (for
     30   example the AIM usericon patch uses this so icons can be stored on
     31   webservers instead of the local filesystem).
     32   
     33   Didn't test this too much, but it seems to work well. Just don't look
     34   at the code that handles HTTP 30x redirects. ;-) The function is
     35   probably not very useful for downloading lots of data since it keeps
     36   everything in a memory buffer until the download is completed (and
     37   can't pass any data or whatever before then). It's very useful for
     38   doing quick requests without blocking the whole program, though. */
     39
    2640#include <glib.h>
    27 
    2841#include "ssl_client.h"
    2942
    3043struct http_request;
    3144
     45/* Your callback function should look like this: */
    3246typedef void (*http_input_function)( struct http_request * );
    3347
     48/* This structure will be filled in by the http_dorequest* functions, and
     49   it will be passed to the callback function. Use the data field to add
     50   your own data. */
    3451struct http_request
    3552{
    36         char *request;
    37         int request_length;
    38         int status_code;
    39         char *status_string;
     53        char *request;          /* The request to send to the server. */
     54        int request_length;     /* Its size. */
     55        int status_code;        /* The numeric HTTP status code. (Or -1
     56                                   if something really went wrong) */
     57        char *status_string;    /* The error text. */
    4058        char *reply_headers;
    4159        char *reply_body;
    42         int body_size;
    43         int finished;
     60        int body_size;          /* The number of bytes in reply_body. */
     61        int finished;           /* Set to non-0 if the request was completed
     62                                   successfully. */
     63       
     64        http_input_function func;
     65        gpointer data;
     66       
     67        /* Please don't touch the things down here, you shouldn't need them. */
    4468       
    4569        void *ssl;
    … …  
    4973        int bytes_written;
    5074        int bytes_read;
    51        
    52         http_input_function func;
    53         gpointer data;
    5475};
    5576
     77/* The _url variant is probably more useful than the raw version. The raw
     78   version is probably only useful if you want to do POST requests or if
     79   you want to add some extra headers. As you can see, HTTPS connections
     80   are also supported (using ssl_client). */
    5681void *http_dorequest( char *host, int port, int ssl, char *request, http_input_function func, gpointer data );
    5782void *http_dorequest_url( char *url_string, http_input_function func, gpointer data );

  • lib/rc4.h

    r04026d4 r0aaca60  
    2323
    2424
     25/* See rc4.c for more information. */
     26
    2527struct rc4_state
    2628{

  • lib/ssl_client.h

    r04026d4 r0aaca60  
    2424*/
    2525
     26/* ssl_client makes it easier to open SSL connections to servers. (It
     27   doesn't offer SSL server functionality yet, but it could be useful
     28   to add it later.) Different ssl_client modules are available, and
     29   ssl_client tries to make them all behave the same. It's very simple
     30   and basic, it just imitates the proxy_connect() function from the
     31   Gaim libs and passes the socket to the program once the handshake
     32   is completed. */
     33
    2634#include <glib.h>
    2735#include "proxy.h"
    2836
     37/* Some generic error codes. Especially SSL_AGAIN is important if you
     38   want to do asynchronous I/O. */
    2939#define SSL_OK            0
    3040#define SSL_NOHANDSHAKE   1
    … …  
    3343extern int ssl_errno;
    3444
     45/* This is what your callback function should look like. */
    3546typedef gboolean (*ssl_input_function)(gpointer, void*, b_input_condition);
    3647
     48
     49/* Connect to host:port, call the given function when the connection is
     50   ready to be used for SSL traffic. This is all done asynchronously, no
     51   blocking I/O! (Except for the DNS lookups, for now...) */
    3752G_MODULE_EXPORT void *ssl_connect( char *host, int port, ssl_input_function func, gpointer data );
     53
     54/* Obviously you need special read/write functions to read data. */
    3855G_MODULE_EXPORT int ssl_read( void *conn, char *buf, int len );
    3956G_MODULE_EXPORT int ssl_write( void *conn, const char *buf, int len );
     57
     58/* Abort the SSL connection and disconnect the socket. Do not use close()
     59   directly, both the SSL library and the peer will be unhappy! */
    4060G_MODULE_EXPORT void ssl_disconnect( void *conn_ );
     61
     62/* Get the fd for this connection, you will usually need it for event
     63   handling. */
    4164G_MODULE_EXPORT int ssl_getfd( void *conn );
     65
     66/* This function returns GAIM_INPUT_READ/WRITE. With SSL connections it's
     67   possible that something has to be read while actually were trying to
     68   write something (think about key exchange/refresh/etc). So when an
     69   SSL operation returned SSL_AGAIN, *always* use this function when
     70   adding an event handler to the queue. (And it should perform exactly
     71   the same action as the handler that just received the SSL_AGAIN.) */
    4272G_MODULE_EXPORT b_input_condition ssl_getdirection( void *conn );
Note: See TracChangeset for help on using the changeset viewer.