curl_ws_send.3 3.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101
  1. .\" **************************************************************************
  2. .\" * _ _ ____ _
  3. .\" * Project ___| | | | _ \| |
  4. .\" * / __| | | | |_) | |
  5. .\" * | (__| |_| | _ <| |___
  6. .\" * \___|\___/|_| \_\_____|
  7. .\" *
  8. .\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
  9. .\" *
  10. .\" * This software is licensed as described in the file COPYING, which
  11. .\" * you should have received as part of this distribution. The terms
  12. .\" * are also available at https://curl.se/docs/copyright.html.
  13. .\" *
  14. .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15. .\" * copies of the Software, and permit persons to whom the Software is
  16. .\" * furnished to do so, under the terms of the COPYING file.
  17. .\" *
  18. .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19. .\" * KIND, either express or implied.
  20. .\" *
  21. .\" * SPDX-License-Identifier: curl
  22. .\" *
  23. .\" **************************************************************************
  24. .\"
  25. .TH curl_ws_send 3 "12 Jun 2022" "libcurl" "libcurl"
  26. .SH NAME
  27. curl_ws_send - send WebSocket data
  28. .SH SYNOPSIS
  29. .nf
  30. #include <curl/easy.h>
  31. CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen,
  32. size_t *sent, curl_off_t fragsize,
  33. unsigned int flags);
  34. .fi
  35. .SH DESCRIPTION
  36. This function call is EXPERIMENTAL.
  37. Send the specific message fragment over an established WebSocket
  38. connection. The \fIbuffer\fP holds the data to send and it is \fIbuflen\fP
  39. number of payload bytes in that memory area.
  40. \fIsent\fP is returned as the number of payload bytes actually sent.
  41. To send a (huge) fragment using multiple calls with partial content per
  42. invoke, set the \fICURLWS_OFFSET\fP bit and the \fIfragsize\fP argument as the
  43. total expected size for the first part, then set the \fICURLWS_OFFSET\fP with
  44. a zero \fIfragsize\fP for the following parts.
  45. If not sending a partial fragment or if this is raw mode, \fIfragsize\fP
  46. should be set to zero.
  47. If \fBCURLWS_RAW_MODE\fP is enabled in \fICURLOPT_WS_OPTIONS(3)\fP, the
  48. \fBflags\fP argument should be set to 0.
  49. To send a message consisting of multiple frames, set the \fICURLWS_CONT\fP bit
  50. in all frames except the final one.
  51. .SH FLAGS
  52. .IP CURLWS_TEXT
  53. The buffer contains text data. Note that this makes a difference to WebSocket
  54. but libcurl itself will not make any verification of the content or
  55. precautions that you actually send valid UTF-8 content.
  56. .IP CURLWS_BINARY
  57. This is binary data.
  58. .IP CURLWS_CONT
  59. This is not the final fragment of the message, which implies that there will
  60. be another fragment coming as part of the same message where this bit is not
  61. set.
  62. .IP CURLWS_CLOSE
  63. Close this transfer.
  64. .IP CURLWS_PING
  65. This is a ping.
  66. .IP CURLWS_PONG
  67. This is a pong.
  68. .IP CURLWS_OFFSET
  69. The provided data is only a partial fragment and there will be more in a
  70. following call to \fIcurl_ws_send()\fP. When sending only a piece of the
  71. fragment like this, the \fIfragsize\fP must be provided with the total
  72. expected fragment size in the first call and it needs to be zero in subsequent
  73. calls.
  74. .SH EXAMPLE
  75. .nf
  76. int ping(CURL *curl, const char *send_payload)
  77. {
  78. size_t sent;
  79. CURLcode result =
  80. curl_ws_send(curl, send_payload, strlen(send_payload), &sent, 0,
  81. CURLWS_PING);
  82. return (int)result;
  83. }
  84. .fi
  85. .SH AVAILABILITY
  86. Added in 7.86.0.
  87. .SH RETURN VALUE
  88. \fICURLE_OK\fP (zero) means that the data was sent properly, non-zero means an
  89. error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors(3)\fP
  90. man page for the full list with descriptions.
  91. .SH "SEE ALSO"
  92. .BR curl_easy_setopt "(3), " curl_easy_perform "(3), "
  93. .BR curl_easy_getinfo "(3), "
  94. .BR curl_ws_recv "(3), " libcurl-ws "(3), "