quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

CURLMOPT_SOCKETFUNCTION.md (3977B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: CURLMOPT_SOCKETFUNCTION
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - CURLMOPT_SOCKETDATA (3)
      9   - CURLMOPT_TIMERFUNCTION (3)
     10   - curl_multi_socket_action (3)
     11 Protocol:
     12   - All
     13 Added-in: 7.15.4
     14 ---
     15 
     16 # NAME
     17 
     18 CURLMOPT_SOCKETFUNCTION - callback informed about what to wait for
     19 
     20 # SYNOPSIS
     21 
     22 ~~~c
     23 #include <curl/curl.h>
     24 
     25 int socket_callback(CURL *easy,      /* easy handle */
     26                     curl_socket_t s, /* socket */
     27                     int what,        /* describes the socket */
     28                     void *clientp,   /* private callback pointer */
     29                     void *socketp);  /* private socket pointer */
     30 
     31 CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callback);
     32 ~~~
     33 
     34 # DESCRIPTION
     35 
     36 Pass a pointer to your callback function, which should match the prototype
     37 shown above.
     38 
     39 When the curl_multi_socket_action(3) function is called, it uses this
     40 callback to inform the application about updates in the socket (file
     41 descriptor) status by doing none, one, or multiple calls to the
     42 **socket_callback**. The callback function gets status updates with changes
     43 since the previous time the callback was called. If the given callback pointer
     44 is set to NULL, no callback is called.
     45 
     46 libcurl then expects the application to monitor the sockets for the specific
     47 activities and tell libcurl again when something happens on one of them. Tell
     48 libcurl by calling curl_multi_socket_action(3).
     49 
     50 This callback may get invoked at any time when interacting with libcurl.
     51 This may even happen after all transfers are done and is *likely* to
     52 happen *during* a call to curl_multi_cleanup(3) when cached connections
     53 are shut down.
     54 
     55 # CALLBACK ARGUMENTS
     56 
     57 *easy* identifies the specific transfer for which this update is related.
     58 Since this callback manages a whole multi handle, an application should not
     59 make assumptions about which particular handle that is passed here. It might
     60 even be an internal easy handle that the application did not add itself.
     61 
     62 *s* is the specific socket this function invocation concerns. If the
     63 **what** argument is not CURL_POLL_REMOVE then it holds information about
     64 what activity on this socket the application is supposed to
     65 monitor. Subsequent calls to this callback might update the **what** bits
     66 for a socket that is already monitored.
     67 
     68 The socket callback should return 0 on success, and -1 on error. If this
     69 callback returns error, **all** transfers currently in progress in this
     70 multi handle are aborted and made to fail.
     71 
     72 **clientp** is set with CURLMOPT_SOCKETDATA(3).
     73 
     74 **socketp** is set with curl_multi_assign(3) or NULL.
     75 
     76 The **what** parameter informs the callback on the status of the given
     77 socket. It can hold one of these values:
     78 
     79 ## CURL_POLL_IN
     80 
     81 Wait for incoming data. For the socket to become readable.
     82 
     83 ## CURL_POLL_OUT
     84 
     85 Wait for outgoing data. For the socket to become writable.
     86 
     87 ## CURL_POLL_INOUT
     88 
     89 Wait for incoming and outgoing data. For the socket to become readable or
     90 writable.
     91 
     92 ## CURL_POLL_REMOVE
     93 
     94 The specified socket/file descriptor is no longer used by libcurl for any
     95 active transfer. It might soon be added again.
     96 
     97 # DEFAULT
     98 
     99 NULL (no callback)
    100 
    101 # %PROTOCOLS%
    102 
    103 # EXAMPLE
    104 
    105 ~~~c
    106 struct priv {
    107   void *ours;
    108 };
    109 
    110 static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp)
    111 {
    112   struct priv *p = sockp;
    113   printf("our ptr: %p\n", p->ours);
    114 
    115   if(what == CURL_POLL_REMOVE) {
    116     /* remove the socket from our collection */
    117   }
    118   if(what & CURL_POLL_IN) {
    119     /* wait for read on this socket */
    120   }
    121   if(what & CURL_POLL_OUT) {
    122     /* wait for write on this socket */
    123   }
    124 
    125   return 0;
    126 }
    127 
    128 int main(void)
    129 {
    130   struct priv setup;
    131   CURLM *multi = curl_multi_init();
    132   /* ... use socket callback and custom pointer */
    133   curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb);
    134   curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup);
    135 }
    136 ~~~
    137 
    138 # %AVAILABILITY%
    139 
    140 # RETURN VALUE
    141 
    142 Returns CURLM_OK.