mirror of
https://github.com/moparisthebest/curl
synced 2024-12-21 23:58:49 -05:00
Initial curl_multi_socket() stuff, #ifdef'ed out for now but committed for
documentational purposes.
This commit is contained in:
Daniel Stenberg
parent
4382204e1b
commit
9a9c07f571
@ -23,16 +23,8 @@
|
||||
* $Id$
|
||||
***************************************************************************/
|
||||
/*
|
||||
This is meant to be the "external" header file. Don't give away any
|
||||
internals here!
|
||||
This is an "external" header file. Don't give away any internals here!
|
||||
|
||||
This document presents a mixture of ideas from at least:
|
||||
- Daniel Stenberg
|
||||
- Steve Dekorte
|
||||
- Sterling Hughes
|
||||
- Ben Greear
|
||||
|
||||
-------------------------------------------
|
||||
GOALS
|
||||
|
||||
o Enable a "pull" interface. The application that uses libcurl decides where
|
||||
@ -82,6 +74,22 @@ extern "C" {
|
||||
|
||||
typedef void CURLM;
|
||||
|
||||
#ifdef HAVE_CURL_MULTI_SOCKET /* this is not set by anything yet */
|
||||
|
||||
#ifndef curl_socket_typedef
|
||||
/* Public socket typedef */
|
||||
#ifdef WIN32
|
||||
typedef SOCKET curl_socket_t;
|
||||
#define CURL_SOCKET_BAD INVALID_SOCKET
|
||||
#else
|
||||
typedef int curl_socket_t;
|
||||
#define CURL_SOCKET_BAD -1
|
||||
#endif
|
||||
#define curl_socket_typedef
|
||||
#endif /* curl_socket_typedef */
|
||||
|
||||
#endif /* HAVE_CURL_MULTI_SOCKET */
|
||||
|
||||
typedef enum {
|
||||
CURLM_CALL_MULTI_PERFORM=-1, /* please call curl_multi_perform() soon */
|
||||
CURLM_OK,
|
||||
@ -113,6 +121,7 @@ typedef struct CURLMsg CURLMsg;
|
||||
* Name: curl_multi_init()
|
||||
*
|
||||
* Desc: inititalize multi-style curl usage
|
||||
*
|
||||
* Returns: a new CURLM handle to use in all 'curl_multi' functions.
|
||||
*/
|
||||
CURL_EXTERN CURLM *curl_multi_init(void);
|
||||
@ -121,6 +130,7 @@ CURL_EXTERN CURLM *curl_multi_init(void);
|
||||
* Name: curl_multi_add_handle()
|
||||
*
|
||||
* Desc: add a standard curl handle to the multi stack
|
||||
*
|
||||
* Returns: CURLMcode type, general multi error code.
|
||||
*/
|
||||
CURL_EXTERN CURLMcode curl_multi_add_handle(CURLM *multi_handle,
|
||||
@ -130,6 +140,7 @@ CURL_EXTERN CURLMcode curl_multi_add_handle(CURLM *multi_handle,
|
||||
* Name: curl_multi_remove_handle()
|
||||
*
|
||||
* Desc: removes a curl handle from the multi stack again
|
||||
*
|
||||
* Returns: CURLMcode type, general multi error code.
|
||||
*/
|
||||
CURL_EXTERN CURLMcode curl_multi_remove_handle(CURLM *multi_handle,
|
||||
@ -141,6 +152,7 @@ CURL_EXTERN CURLMcode curl_multi_remove_handle(CURLM *multi_handle,
|
||||
* Desc: Ask curl for its fd_set sets. The app can use these to select() or
|
||||
* poll() on. We want curl_multi_perform() called as soon as one of
|
||||
* them are ready.
|
||||
*
|
||||
* Returns: CURLMcode type, general multi error code.
|
||||
*/
|
||||
CURL_EXTERN CURLMcode curl_multi_fdset(CURLM *multi_handle,
|
||||
@ -175,6 +187,7 @@ CURL_EXTERN CURLMcode curl_multi_perform(CURLM *multi_handle,
|
||||
* touch any individual easy handles in any way. We need to define
|
||||
* in what state those handles will be if this function is called
|
||||
* in the middle of a transfer.
|
||||
*
|
||||
* Returns: CURLMcode type, general multi error code.
|
||||
*/
|
||||
CURL_EXTERN CURLMcode curl_multi_cleanup(CURLM *multi_handle);
|
||||
@ -211,16 +224,107 @@ CURL_EXTERN CURLMsg *curl_multi_info_read(CURLM *multi_handle,
|
||||
int *msgs_in_queue);
|
||||
|
||||
/*
|
||||
* NAME curl_multi_strerror()
|
||||
* Name: curl_multi_strerror()
|
||||
*
|
||||
* DESCRIPTION
|
||||
* Desc: The curl_multi_strerror function may be used to turn a CURLMcode
|
||||
* value into the equivalent human readable error string. This is
|
||||
* useful for printing meaningful error messages.
|
||||
*
|
||||
* The curl_multi_strerror function may be used to turn a CURLMcode value
|
||||
* into the equivalent human readable error string. This is useful
|
||||
* for printing meaningful error messages.
|
||||
* Returns: A pointer to a zero-terminated error message.
|
||||
*/
|
||||
CURL_EXTERN const char *curl_multi_strerror(CURLMcode);
|
||||
|
||||
#ifdef HAVE_CURL_MULTI_SOCKET
|
||||
/*
|
||||
* Name: curl_multi_socket() and
|
||||
* curl_multi_socket_all()
|
||||
*
|
||||
* Desc: An alternative version of curl_multi_perform() that allows the
|
||||
* application to pass in one of the file descriptors that have been
|
||||
* detected to have "action" on them and let libcurl perform. This
|
||||
* allows libcurl to not have to scan through all possible file
|
||||
* descriptors to check for this. The app is recommended to pass in
|
||||
* the 'easy' argument (or set it to CURL_EASY_NONE) to make libcurl
|
||||
* figure out the internal structure even faster and easier. If the
|
||||
* easy argument is set to something else than CURL_EASY_NONE, the
|
||||
* 's' (socket) argument will be ignored by libcurl.
|
||||
*
|
||||
* It also informs the application about updates in the socket (file
|
||||
* descriptor) status by doing none, one or multiple calls to the
|
||||
* curl_socket_callback. It thus updates the status with changes
|
||||
* since the previous time this function was used. If 'callback' is
|
||||
* NULL, no callback will be called. A status change may also be a
|
||||
* new timeout only, having the same IN/OUT status as before.
|
||||
*
|
||||
* If a previous wait for socket action(s) timed out, you should call
|
||||
* this function with the socket argument set to
|
||||
* CURL_SOCKET_TIMEOUT. If you want to force libcurl to (re-)check
|
||||
* all its internal sockets, and call the callback with status for
|
||||
* all sockets no matter what the previous state is, you call
|
||||
* curl_multi_socket_all() instead.
|
||||
*
|
||||
* curl_multi_perform() is thus the equivalent of calling
|
||||
* curl_multi_socket_all(handle, NULL, NULL);
|
||||
*
|
||||
* IMPLEMENTATION: libcurl will need an internal hash table to map
|
||||
* socket numbers to internal easy handles for the cases when 'easy'
|
||||
* is set to CURL_EASY_NONE.
|
||||
*
|
||||
* Regarding the timeout argument in the callback: it is the timeout
|
||||
* (in milliseconds) for waiting on action on this socket (and the
|
||||
* given time period starts when the callback is called) until you
|
||||
* should call curl_multi_socket() with the timeout stuff mentioned
|
||||
* above. If "actions" happens on the socket before the timeout
|
||||
* happens, remember that the timout timer keeps ticking until told
|
||||
* otherwise.
|
||||
*
|
||||
* The "what" argument has one of five values:
|
||||
*
|
||||
* 0 CURL_POLL_NONE (0) - register, not interested in readiness
|
||||
* 1 CURL_POLL_IN - register, interested in read readiness
|
||||
* 2 CURL_POLL_OUT - register, interested in write readiness
|
||||
* 3 CURL_POLL_INOUT - register, interested in both
|
||||
* 4 CURL_POLL_REMOVE - deregister
|
||||
*/
|
||||
#define CURL_POLL_NONE 0
|
||||
#define CURL_POLL_IN 1
|
||||
#define CURL_POLL_OUT 2
|
||||
#define CURL_POLL_INOUT 3
|
||||
#define CURL_POLL_REMOVE 4
|
||||
|
||||
#define CURL_EASY_NONE (CURL *)0
|
||||
#define CURL_EASY_TIMEOUT (CURL *)0
|
||||
#define CURL_SOCKET_TIMEOUT CURL_SOCKET_BAD
|
||||
|
||||
typedef int (*curl_socket_callback)(CURL *easy, /* easy handle */
|
||||
curl_socket_t s, /* socket */
|
||||
int what, /* see above */
|
||||
long ms, /* timeout for wait */
|
||||
void *userp); /* "private" pointer */
|
||||
|
||||
CURLMcode curl_multi_socket(CURLM *multi_handle,
|
||||
curl_socket_t s,
|
||||
CURL *easy,
|
||||
curl_socket_callback callback,
|
||||
void *userp); /* passed to callback */
|
||||
|
||||
CURLMcode curl_multi_socket_all(CURLM *multi_handle,
|
||||
curl_socket_callback callback,
|
||||
void *userp); /* passed to callback */
|
||||
|
||||
/*
|
||||
* Name: curl_multi_timeout()
|
||||
*
|
||||
* Desc: Returns the maximum number of milliseconds the app is allowed to
|
||||
* wait before curl_multi_socket() or curl_multi_perform() must be
|
||||
* called (to allow libcurl's timed events to take place).
|
||||
*
|
||||
* Returns: CURLM error code.
|
||||
*/
|
||||
CURLMcode curl_multi_timeout(CURLM *multi_handle, long *milliseconds);
|
||||
|
||||
#endif /* HAVE_CURL_MULTI_SOCKET */
|
||||
|
||||
#ifdef __cplusplus
|
||||
} /* end of extern "C" */
|
||||
#endif
|
||||
|
||||
Loading…
Reference in New Issue
Block a user