* $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
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,
* 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);
* 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,
* 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,
* 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,
* 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);
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
projects / curl / commitdiff