quickjs-tart

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

curl_ws_send.md (4178B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: curl_ws_send
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - curl_easy_getinfo (3)
      9   - curl_easy_perform (3)
     10   - curl_easy_setopt (3)
     11   - curl_ws_recv (3)
     12   - libcurl-ws (3)
     13 Protocol:
     14   - WS
     15 Added-in: 7.86.0
     16 ---
     17 
     18 # NAME
     19 
     20 curl_ws_send - send WebSocket data
     21 
     22 # SYNOPSIS
     23 
     24 ~~~c
     25 #include <curl/curl.h>
     26 
     27 CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen,
     28                       size_t *sent, curl_off_t fragsize,
     29                       unsigned int flags);
     30 ~~~
     31 
     32 # DESCRIPTION
     33 
     34 Send the specific message chunk over an established WebSocket
     35 connection. *buffer* must point to a valid memory location containing
     36 (at least) *buflen* bytes of payload memory.
     37 
     38 *sent* is set to the number of payload bytes actually sent. If the return value
     39 is **CURLE_OK** but *sent* is less than the given *buflen*, libcurl was unable
     40 to consume the complete payload in a single call. In this case the application
     41 must call this function again until all payload is processed. *buffer* and
     42 *buflen* must be updated on every following invocation to only point to the
     43 remaining piece of the payload.
     44 
     45 *fragsize* should always be set to zero unless a (huge) frame shall be sent
     46 using multiple calls with partial content per call explicitly. In that
     47 case you must set the *CURLWS_OFFSET* bit and set the *fragsize* as documented
     48 in the section on *CURLWS_OFFSET* below.
     49 
     50 *flags* must contain at least one flag indicating the type of the message.
     51 To send a fragmented message consisting of multiple frames, additionally set
     52 the *CURLWS_CONT* bit in all frames except the final one. The appropriate
     53 message type bit should be set in every frame of a fragmented message without
     54 exemption. Omitting the message type for continuation frames of a fragmented
     55 message is only supported for backwards compatibility and highly discouraged.
     56 
     57 For more details on the supported flags see below and in curl_ws_meta(3).
     58 
     59 If *CURLWS_RAW_MODE* is enabled in CURLOPT_WS_OPTIONS(3), the
     60 *flags* argument should be set to 0.
     61 
     62 Warning: while it is possible to invoke this function from a callback,
     63 such a call is blocking in this situation, e.g. only returns after all data
     64 has been sent or an error is encountered.
     65 
     66 # FLAGS
     67 
     68 Supports all flags documented in curl_ws_meta(3) and additionally the following
     69 flags.
     70 
     71 ## CURLWS_OFFSET
     72 
     73 The provided data is only a partial frame and there is more coming in a
     74 following call to *curl_ws_send()*. When sending only a piece of the
     75 frame like this, the *fragsize* must be provided with the total
     76 expected frame size in the first call and must be zero in all subsequent
     77 calls.
     78 
     79 # %PROTOCOLS%
     80 
     81 # EXAMPLE
     82 
     83 ~~~c
     84 #include <string.h> /* for strlen */
     85 
     86 int main(void)
     87 {
     88   const char *buffer = "PAYLOAD";
     89   size_t offset = 0;
     90   CURLcode res = CURLE_OK;
     91   CURL *curl = curl_easy_init();
     92 
     93   curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/");
     94   curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L);
     95   /* start HTTPS connection and upgrade to WSS, then return control */
     96   curl_easy_perform(curl);
     97 
     98   while(!res) {
     99     size_t sent;
    100     res = curl_ws_send(curl, buffer + offset, strlen(buffer) - offset, &sent,
    101                        0, CURLWS_TEXT);
    102     offset += sent;
    103 
    104     if(res == CURLE_OK) {
    105       if(offset == strlen(buffer))
    106         break; /* finished sending */
    107     }
    108 
    109     if(res == CURLE_AGAIN)
    110       /* in real application: wait for socket here, e.g. using select() */
    111       res = CURLE_OK;
    112   }
    113 
    114   curl_easy_cleanup(curl);
    115   return (int)res;
    116 }
    117 ~~~
    118 
    119 # %AVAILABILITY%
    120 
    121 # RETURN VALUE
    122 
    123 This function returns a CURLcode indicating success or error.
    124 
    125 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
    126 libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
    127 there can be an error message stored in the error buffer when non-zero is
    128 returned.
    129 
    130 Instead of blocking, the function returns **CURLE_AGAIN**. The correct
    131 behavior is then to wait for the socket to signal readability before calling
    132 this function again.
    133 
    134 Any other non-zero return value indicates an error. See the libcurl-errors(3)
    135 man page for the full list with descriptions.