source: branches/1.4x/libtransmission/iobuf.h @ 7177

Last change on this file since 7177 was 7177, checked in by charles, 12 years ago

(1.4x libT) backport the bandwidth fixes back to the 1.4x branch, pass #3: add the new files bandwidth.[ch] and iobuf.[ch]

File size: 4.6 KB
Line 
1/*
2 * Copyright (c) 2002-2004 Niels Provos <provos@citi.umich.edu>
3 * All rights reserved.
4 *
5 * Transmission modifications and new bugs by Charles Kerr.
6 * Source: libevent's "patches-1.4" branch, svn revision 949
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 * 1. Redistributions of source code must retain the above copyright
12 *    notice, this list of conditions and the following disclaimer.
13 * 2. Redistributions in binary form must reproduce the above copyright
14 *    notice, this list of conditions and the following disclaimer in the
15 *    documentation and/or other materials provided with the distribution.
16 * 3. The name of the author may not be used to endorse or promote products
17 *    derived from this software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
20 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
23 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30
31#ifndef __TRANSMISSION__
32#error only libtransmission should #include this header.
33#endif
34
35#ifndef TR_EVBUFFER_H
36#define TR_EVBUFFER_H
37
38/**
39 * tr_iobuf is an i/o convenience wrapper similar to libevent's "bufferevent".
40 * it provides two evbuffers, one for writing and one for reading, and handles
41 * pumping them to/from the given fd.
42 *
43 * this class differs from bufferevent in two major ways:
44 * 1. the action callbacks include the number of bytes transferred
45 * 2. the up/down speeds are directly constrained by our `bandwidth' object
46 * 3. the implementation is hidden in the .c file
47 */
48struct tr_iobuf;
49
50struct evbuffer;
51struct tr_bandwidth;
52struct tr_session;
53
54/** @brief returns the input evbuffer to that we can read from */
55struct evbuffer* tr_iobuf_input( struct tr_iobuf * iobuf );
56
57/** @brief returns the output evbuffer that we can write to */
58struct evbuffer* tr_iobuf_output( struct tr_iobuf * iobuf );
59
60/** @brief prototype for the callbacks invoked when bytes have been read or written
61    @see tr_iobuf_new
62    @see tr_iobuf_setcb */
63typedef void (*tr_iobuf_cb)( struct tr_iobuf*, size_t bytes_transferred, void* );
64
65/** @brief prototype for the callback invoked on error
66    @see tr_iobuf_new
67    @see tr_iobuf_setcb */
68typedef void (*tr_iobuf_error_cb)( struct tr_iobuf*, short what, void* );
69
70/** @brief create a new tr_iobuf object. */
71struct tr_iobuf* tr_iobuf_new( struct tr_handle     * session,
72                               struct tr_bandwidth  * bandwidth, 
73                               int                    fd,
74                               short                  event,
75                               tr_iobuf_cb            readcb,
76                               tr_iobuf_cb            writecb,
77                               tr_iobuf_error_cb      errorcb,
78                               void                 * cbarg );
79
80/** @brief destroy a tr_iobuf object. */
81void tr_iobuf_free( struct tr_iobuf * iobuf );
82
83/** @brief change the number of seconds it takes for a read/write to timeout */
84void tr_iobuf_settimeout( struct tr_iobuf  * iobuf,
85                          int                timeout_read,
86                          int                timeout_write );
87
88/** @brief set the bandwidth object that limits this iobuf's read/write speeds */
89void tr_iobuf_set_bandwidth( struct tr_iobuf      * iobuf,
90                             struct tr_bandwidth  * bandwidth );
91
92/** @brief change the callbacks invoked by this iobuf on error and bytes transferred */
93void tr_iobuf_setcb( struct tr_iobuf    * iobuf,
94                     tr_iobuf_cb          readcb,
95                     tr_iobuf_cb          writecb,
96                     tr_iobuf_error_cb    errorcb,
97                     void               * cbarg );
98
99/** @brief tell the iobuf to poll for certain states.
100    @brief event may be EV_READ, EV_WRITE, or EV_READ|EV_WRITE */
101int tr_iobuf_enable( struct tr_iobuf * iobuf, short event );
102
103/** @brief tell the iobuf to stop polling for certain states.
104    @brief event may be EV_READ, EV_WRITE, or EV_READ|EV_WRITE */
105int tr_iobuf_disable( struct tr_iobuf * iobuf, short event );
106
107#endif
Note: See TracBrowser for help on using the repository browser.