mingw/share/man/man3/curl_multi_socket.3

   1 .\" $Id: curl_multi_socket.3,v 1.8 2007-04-16 16:34:08 bagder Exp $
   2 .\"
   3 .TH curl_multi_socket 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual"
   4 .SH NAME
   5 curl_multi_socket \- reads/writes available data
   6 .SH SYNOPSIS
   7 .nf
   8 #include <curl/curl.h>
   9
  10 CURLMcode curl_multi_socket_action(CURLM * multi_handle,
  11                                    curl_socket_t sockfd, int ev_bitmask,
  12                                    int *running_handles);
  13
  14 CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd,
  15                             int *running_handles);
  16
  17 CURLMcode curl_multi_socket_all(CURLM *multi_handle,
  18                                 int *running_handles);
  19 .fi
  20 .SH DESCRIPTION
  21 Alternative versions of \fIcurl_multi_perform(3)\fP that allows the
  22 application to pass in the file descriptor/socket that has been detected to
  23 have \&"action" on it and let libcurl perform. This allows libcurl to not have
  24 to scan through all possible file descriptors to check for action. When the
  25 application has detected action on a socket handled by libcurl, it should call
  26 \fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument set to the
  27 socket with the action. When the events on a socket are known, they can be
  28 passed as an events bitmask \fBev_bitmask\fP by first setting \fBev_bitmask\fP
  29 to 0, and then adding using bitwise OR (|) any combination of events to be
  30 choosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the
  31 events on a socket are unknown, pass 0 instead, and libcurl will test the
  32 descriptor internally.
  33
  34 At return, the int \fBrunning_handles\fP points to will contain the number of
  35 still running easy handles within the multi handle. When this number reaches
  36 zero, all transfers are complete/done. Note that when you call
  37 \fIcurl_multi_socket_action(3)\fP on a specific socket and the counter
  38 decreases by one, it DOES NOT necessarily mean that this exact socket/transfer
  39 is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out
  40 which easy handle that completed.
  41
  42 The curl_multi_socket functions inform the application about updates in the
  43 socket (file descriptor) status by doing none, one or multiple calls to the
  44 socket callback function set with the CURLMOPT_SOCKETFUNCTION option to
  45 \fIcurl_multi_setopt(3)\fP. They update the status with changes since the
  46 previous time this function was called.
  47
  48 To force libcurl to (re-)check all its internal sockets and transfers instead
  49 of just a single one, you call \fBcurl_multi_socket_all(3)\fP. This is
  50 typically done as the first function call before the application has any
  51 knowledge about what sockets libcurl uses.
  52
  53 Applications should call \fBcurl_multi_timeout(3)\fP to figure out how long to
  54 wait for socket actions \- at most \- before doing the timeout action: call
  55 the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP argument set to
  56 CURL_SOCKET_TIMEOUT.
  57
  58 Usage of \fIcurl_multi_socket(3)\fP is depricated, whereas the function is
  59 equivalent to \fIcurl_multi_socket_action(3)\fP, when \fBev_bitmask\fP is set
  60 to 0.
  61
  62 .SH "CALLBACK DETAILS"
  63
  64 The socket \fBcallback\fP function uses a prototype like this
  65 .nf
  66
  67   int curl_socket_callback(CURL *easy,      /* easy handle */
  68                            curl_socket_t s, /* socket */
  69                            int action,      /* see values below */
  70                            void *userp,    /* private callback pointer */
  71                            void *socketp); /* private socket pointer */
  72
  73 .fi
  74 The callback MUST return 0.
  75
  76 The \fIeasy\fP argument is a pointer to the easy handle that deals with this
  77 particular socket. Note that a single handle may work with several sockets
  78 simultaneously.
  79
  80 The \fIs\fP argument is the actual socket value as you use it within your
  81 system.
  82
  83 The \fIaction\fP argument to the callback has one of five values:
  84 .RS
  85 .IP "CURL_POLL_NONE (0)"
  86 register, not interested in readiness (yet)
  87 .IP "CURL_POLL_IN (1)"
  88 register, interested in read readiness
  89 .IP "CURL_POLL_OUT (2)"
  90 register, interested in write readiness
  91 .IP "CURL_POLL_INOUT (3)"
  92 register, interested in both read and write readiness
  93 .IP "CURL_POLL_REMOVE (4)"
  94 deregister
  95 .RE
  96
  97 The \fIsocketp\fP argument is a private pointer you have previously set with
  98 \fIcurl_multi_assign(3)\fP to be associated with the \fIs\fP socket. If no
  99 pointer has been set, socketp will be NULL. This argument is of course a
 100 service to applications that want to keep certain data or structs that are
 101 strictly associated to the given socket.
 102
 103 The \fIuserp\fP argument is a private pointer you have previously set with
 104 \fIcurl_multi_setopt(3)\fP and the CURLMOPT_SOCKETDATA option.
 105 .SH "RETURN VALUE"
 106 CURLMcode type, general libcurl multi interface error code.
 107
 108 If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you
 109 should call \fIcurl_multi_perform\fP again, before you wait for more actions
 110 on libcurl's sockets. You don't have to do it immediately, but the return code
 111 means that libcurl may have more data available to return or that there may be
 112 more data to send off before it is "satisfied".
 113
 114 NOTE that this only returns errors etc regarding the whole multi stack. There
 115 might still have occurred problems on individual transfers even when this
 116 function returns OK.
 117 .SH "TYPICAL USAGE"
 118 1. Create a multi handle
 119
 120 2. Set the socket callback with CURLMOPT_SOCKETFUNCTION
 121
 122 3. Add easy handles
 123
 124 4. Call curl_multi_socket_all() first once
 125
 126 5. Setup a "collection" of sockets to supervise when your socket
 127 callback is called.
 128
 129 6. Use curl_multi_timeout() to figure out how long to wait for action
 130
 131 7. Wait for action on any of libcurl's sockets
 132
 133 8, When action happens, call curl_multi_socket_action() for the socket(s) that got
 134 action.
 135
 136 9. Go back to step 6.
 137 .SH AVAILABILITY
 138 This function was added in libcurl 7.15.4, although deemed stablesince 7.16.0.
 139
 140 \fIcurl_multi_socket(3)\fP is deprecated, use
 141 \fIcurl_multi_socket_action(3)\fP instead!
 142 .SH "SEE ALSO"
 143 .BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
 144 .BR curl_multi_fdset "(3), " curl_multi_info_read "(3)"