aboutsummaryrefslogtreecommitdiff
path: root/doc/libmicrohttpd.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/libmicrohttpd.texi')
-rw-r--r--doc/libmicrohttpd.texi1281
1 files changed, 1281 insertions, 0 deletions
diff --git a/doc/libmicrohttpd.texi b/doc/libmicrohttpd.texi
index 8e275a3b..a6bd12eb 100644
--- a/doc/libmicrohttpd.texi
+++ b/doc/libmicrohttpd.texi
@@ -67,6 +67,7 @@ Free Documentation License".
67* microhttpd-post:: Adding a @code{POST} processor. 67* microhttpd-post:: Adding a @code{POST} processor.
68* microhttpd-info:: Obtaining and modifying status information. 68* microhttpd-info:: Obtaining and modifying status information.
69* microhttpd-util:: Utilities. 69* microhttpd-util:: Utilities.
70* microhttpd-websocket:: Websockets.
70 71
71Appendices 72Appendices
72 73
@@ -1246,6 +1247,493 @@ list.
1246@end deftp 1247@end deftp
1247 1248
1248 1249
1250@deftp {Enumeration} MHD_WEBSOCKET_FLAG
1251@cindex websocket
1252Options for the MHD websocket stream.
1253
1254This is used for initialization of a websocket stream when calling
1255@code{MHD_websocket_stream_init} or @code{MHD_websocket_stream_init2} and
1256alters the behavior of the websocket stream.
1257
1258Note that websocket streams are only available if you include the header file
1259@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
1260
1261@table @code
1262@item MHD_WEBSOCKET_FLAG_SERVER
1263The websocket stream is initialized in server mode (default).
1264Thus all outgoing payload will not be masked.
1265All incoming payload must be masked.
1266
1267This flag cannot be used together with @code{MHD_WEBSOCKET_FLAG_CLIENT}.
1268
1269@item MHD_WEBSOCKET_FLAG_CLIENT
1270The websocket stream is initialized in client mode.
1271You will usually never use that mode in combination with @emph{libmicrohttpd},
1272because @emph{libmicrohttpd} provides a server and not a client.
1273In client mode all outgoing payload will be masked
1274(XOR-ed with random values).
1275All incoming payload must be unmasked.
1276If you use this mode, you must always call @code{MHD_websocket_stream_init2}
1277instead of @code{MHD_websocket_stream_init}, because you need
1278to pass a random number generator callback function for masking.
1279
1280This flag cannot be used together with @code{MHD_WEBSOCKET_FLAG_SERVER}.
1281
1282@item MHD_WEBSOCKET_FLAG_NO_FRAGMENTS
1283You don't want to get fragmented data while decoding (default).
1284Fragmented frames will be internally put together until
1285they are complete.
1286Whether or not data is fragmented is decided
1287by the sender of the data during encoding.
1288
1289This cannot be used together with @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}.
1290
1291@item MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS
1292You want fragmented data, if it appears while decoding.
1293You will receive the content of the fragmented frame,
1294but if you are decoding text, you will never get an unfinished
1295UTF-8 sequence (if the sequence appears between two fragments).
1296Instead the text will end before the unfinished UTF-8 sequence.
1297With the next fragment, which finishes the UTF-8 sequence,
1298you will get the complete UTF-8 sequence.
1299
1300This cannot be used together with @code{MHD_WEBSOCKET_FLAG_NO_FRAGMENTS}.
1301
1302@item MHD_WEBSOCKET_FLAG_GENERATE_CLOSE_FRAMES_ON_ERROR
1303If the websocket stream becomes invalid during decoding due to
1304protocol errors, a matching close frame will automatically
1305be generated.
1306The close frame will be returned via the parameters
1307@code{payload} and @code{payload_len} of @code{MHD_websocket_decode} and
1308the return value is negative (a value of @code{enum MHD_WEBSOCKET_STATUS}).
1309
1310The generated close frame must be freed by the caller
1311with @code{MHD_websocket_free}.
1312
1313@end table
1314@end deftp
1315
1316
1317@deftp {Enumeration} MHD_WEBSOCKET_FRAGMENTATION
1318@cindex websocket
1319This enumeration is used to specify the fragmentation behavior
1320when encoding of data (text/binary) for a websocket stream.
1321This is used with @code{MHD_websocket_encode_text} or
1322@code{MHD_websocket_encode_binary}.
1323
1324Note that websocket streams are only available if you include the header file
1325@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
1326
1327@table @code
1328@item MHD_WEBSOCKET_FRAGMENTATION_NONE
1329You don't want to use fragmentation.
1330The encoded frame consists of only one frame.
1331
1332@item MHD_WEBSOCKET_FRAGMENTATION_FIRST
1333You want to use fragmentation.
1334The encoded frame is the first frame of
1335a series of data frames of the same type
1336(text or binary).
1337You may send control frames (ping, pong or close)
1338between these data frames.
1339
1340@item MHD_WEBSOCKET_FRAGMENTATION_FOLLOWING
1341You want to use fragmentation.
1342The encoded frame is not the first frame of
1343the series of data frames, but also not the last one.
1344You may send control frames (ping, pong or close)
1345between these data frames.
1346
1347@item MHD_WEBSOCKET_FRAGMENTATION_LAST
1348You want to use fragmentation.
1349The encoded frame is the last frame of
1350the series of data frames, but also not the first one.
1351After this frame, you may send all types of frames again.
1352
1353@end table
1354@end deftp
1355
1356
1357@deftp {Enumeration} MHD_WEBSOCKET_STATUS
1358@cindex websocket
1359This enumeration is used for the return value of almost
1360every websocket stream function.
1361Errors are negative and values equal to or above zero mean a success.
1362Positive values are only used by @code{MHD_websocket_decode}.
1363
1364Note that websocket streams are only available if you include the header file
1365@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
1366
1367@table @code
1368@item MHD_WEBSOCKET_STATUS_OK
1369The call succeeded.
1370Especially for @code{MHD_websocket_decode} this means that no error occurred,
1371but also no frame has been completed yet.
1372For other functions this means simply a success.
1373
1374@item MHD_WEBSOCKET_STATUS_TEXT_FRAME
1375@code{MHD_websocket_decode} has decoded a text frame.
1376The parameters @code{payload} and @code{payload_len} are filled with
1377the decoded text (if any).
1378You must free the returned @code{payload} after use with
1379@code{MHD_websocket_free}.
1380
1381@item MHD_WEBSOCKET_STATUS_BINARY_FRAME
1382@code{MHD_websocket_decode} has decoded a binary frame.
1383The parameters @code{payload} and @code{payload_len} are filled with
1384the decoded binary data (if any).
1385You must free the returned @code{payload} after use with
1386@code{MHD_websocket_free}.
1387
1388@item MHD_WEBSOCKET_STATUS_CLOSE_FRAME
1389@code{MHD_websocket_decode} has decoded a close frame.
1390This means you must close the socket using @code{MHD_upgrade_action}
1391with @code{MHD_UPGRADE_ACTION_CLOSE}.
1392You may respond with a close frame before closing.
1393The parameters @code{payload} and @code{payload_len} are filled with
1394the close reason (if any).
1395The close reason starts with a two byte sequence of close code
1396in network byte order (see @code{enum MHD_WEBSOCKET_CLOSEREASON}).
1397After these two bytes a UTF-8 encoded close reason may follow.
1398You can call @code{MHD_websocket_split_close_reason} to split that
1399close reason.
1400You must free the returned @code{payload} after use with
1401@code{MHD_websocket_free}.
1402
1403@item MHD_WEBSOCKET_STATUS_PING_FRAME
1404@code{MHD_websocket_decode} has decoded a ping frame.
1405You should respond to this with a pong frame.
1406The pong frame must contain the same binary data as
1407the corresponding ping frame (if it had any).
1408The parameters @code{payload} and @code{payload_len} are filled with
1409the binary ping data (if any).
1410You must free the returned @code{payload} after use with
1411@code{MHD_websocket_free}.
1412
1413@item MHD_WEBSOCKET_STATUS_PONG_FRAME
1414@code{MHD_websocket_decode} has decoded a pong frame.
1415You should usually only receive pong frames if you sent
1416a ping frame before.
1417The binary data should be equal to your ping frame and can be
1418used to distinguish the response if you sent multiple ping frames.
1419The parameters @code{payload} and @code{payload_len} are filled with
1420the binary pong data (if any).
1421You must free the returned @code{payload} after use with
1422@code{MHD_websocket_free}.
1423
1424@item MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT
1425@code{MHD_websocket_decode} has decoded a text frame fragment.
1426The parameters @code{payload} and @code{payload_len} are filled with
1427the decoded text (if any).
1428This is like @code{MHD_WEBSOCKET_STATUS_TEXT_FRAME}, but it can only
1429appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS} during
1430the call of @code{MHD_websocket_stream_init} or
1431@code{MHD_websocket_stream_init2}.
1432You must free the returned @code{payload} after use with
1433@code{MHD_websocket_free}.
1434
1435@item MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT
1436@code{MHD_websocket_decode} has decoded a binary frame fragment.
1437The parameters @code{payload} and @code{payload_len} are filled with
1438the decoded binary data (if any).
1439This is like @code{MHD_WEBSOCKET_STATUS_BINARY_FRAME}, but it can only
1440appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS} during
1441the call of @code{MHD_websocket_stream_init} or
1442@code{MHD_websocket_stream_init2}.
1443You must free the returned @code{payload} after use with
1444@code{MHD_websocket_free}.
1445
1446@item MHD_WEBSOCKET_STATUS_TEXT_NEXT_FRAGMENT
1447@code{MHD_websocket_decode} has decoded the next text frame fragment.
1448The parameters @code{payload} and @code{payload_len} are filled with
1449the decoded text (if any).
1450This is like @code{MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT}, but it appears
1451only after the first and before the last fragment of a series of fragments.
1452It can only appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
1453during the call of @code{MHD_websocket_stream_init} or
1454@code{MHD_websocket_stream_init2}.
1455You must free the returned @code{payload} after use with
1456@code{MHD_websocket_free}.
1457
1458@item MHD_WEBSOCKET_STATUS_BINARY_NEXT_FRAGMENT
1459@code{MHD_websocket_decode} has decoded the next binary frame fragment.
1460The parameters @code{payload} and @code{payload_len} are filled with
1461the decoded binary data (if any).
1462This is like @code{MHD_WEBSOCKET_STATUS_BINARY_FIRST_FRAGMENT}, but it appears
1463only after the first and before the last fragment of a series of fragments.
1464It can only appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
1465during the call of @code{MHD_websocket_stream_init} or
1466@code{MHD_websocket_stream_init2}.
1467You must free the returned @code{payload} after use with
1468@code{MHD_websocket_free}.
1469
1470@item MHD_WEBSOCKET_STATUS_TEXT_LAST_FRAGMENT
1471@code{MHD_websocket_decode} has decoded the last text frame fragment.
1472The parameters @code{payload} and @code{payload_len} are filled with
1473the decoded text (if any).
1474This is like @code{MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT}, but it appears
1475only for the last fragment of a series of fragments.
1476It can only appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
1477during the call of @code{MHD_websocket_stream_init} or
1478@code{MHD_websocket_stream_init2}.
1479You must free the returned @code{payload} after use with
1480@code{MHD_websocket_free}.
1481
1482@item MHD_WEBSOCKET_STATUS_BINARY_LAST_FRAGMENT
1483@code{MHD_websocket_decode} has decoded the last binary frame fragment.
1484The parameters @code{payload} and @code{payload_len} are filled with
1485the decoded binary data (if any).
1486This is like @code{MHD_WEBSOCKET_STATUS_BINARY_FIRST_FRAGMENT}, but it appears
1487only for the last fragment of a series of fragments.
1488It can only appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
1489during the call of @code{MHD_websocket_stream_init} or
1490@code{MHD_websocket_stream_init2}.
1491You must free the returned @code{payload} after use with
1492@code{MHD_websocket_free}.
1493
1494@item MHD_WEBSOCKET_STATUS_PROTOCOL_ERROR
1495The call failed and the stream is invalid now for decoding.
1496You must close the websocket now using @code{MHD_upgrade_action}
1497with @code{MHD_UPGRADE_ACTION_CLOSE}.
1498You may send a close frame before closing.
1499This is only used by @code{MHD_websocket_decode} and happens
1500if the stream contains errors (i. e. invalid byte data).
1501
1502@item MHD_WEBSOCKET_STATUS_STREAM_BROKEN
1503You tried to decode something, but the stream has already
1504been marked invalid.
1505You must close the websocket now using @code{MHD_upgrade_action}
1506with @code{MHD_UPGRADE_ACTION_CLOSE}.
1507You may send a close frame before closing.
1508This is only used by @code{MHD_websocket_decode} and happens
1509if you call @code{MDM_websocket_decode} again after
1510has been invalidated.
1511You can call @code{MHD_websocket_stream_is_valid} at any time
1512to check whether a stream is invalid or not.
1513
1514@item MHD_WEBSOCKET_STATUS_MEMORY_ERROR
1515A memory allocation failed. The stream remains valid.
1516If this occurred while decoding, the decoding could be
1517possible later if enough memory is available.
1518This could happen while decoding if you received a too big data frame.
1519You could try to specify max_payload_size during the call of
1520@code{MHD_websocket_stream_init} or @code{MHD_websocket_stream_init2} to
1521avoid this and close the websocket instead.
1522
1523@item MHD_WEBSOCKET_STATUS_PARAMETER_ERROR
1524You passed invalid parameters during the function call
1525(i. e. a NULL pointer for a required parameter).
1526The stream remains valid.
1527
1528@item MHD_WEBSOCKET_STATUS_MAXIMUM_SIZE_EXCEEDED
1529The maximum payload size has been exceeded.
1530If you got this return code from @code{MHD_websocket_decode} then
1531the stream becomes invalid and the websocket must be closed
1532using @code{MHD_upgrade_action} with @code{MHD_UPGRADE_ACTION_CLOSE}.
1533You may send a close frame before closing.
1534The maximum payload size is specified during the call of
1535@code{MHD_websocket_stream_init} or @code{MHD_websocket_stream_init2}.
1536This can also appear if you specified 0 as maximum payload size
1537when the message is greater than the maximum allocatable memory size
1538(i. e. more than 4 GiB on 32 bit systems).
1539If you got this return code from @code{MHD_websocket_encode_close},
1540@code{MHD_websocket_encode_ping} or @code{MHD_websocket_encode_pong} then
1541you passed to much payload data. The stream remains valid then.
1542
1543@item MHD_WEBSOCKET_STATUS_UTF8_ENCODING_ERROR
1544An UTF-8 sequence is invalid.
1545If you got this return code from @code{MHD_websocket_decode} then
1546the stream becomes invalid and you must close the websocket
1547using @code{MHD_upgrade_action} with @code{MHD_UPGRADE_ACTION_CLOSE}.
1548You may send a close frame before closing.
1549If you got this from @code{MHD_websocket_encode_text} or
1550@code{MHD_websocket_encode_close} then you passed invalid UTF-8 text.
1551The stream remains valid then.
1552
1553@item MHD_WEBSOCKET_STATUS_NO_WEBSOCKET_HANDSHAKE_HEADER
1554A check routine for the HTTP headers came to the conclusion that
1555the header value isn't valid for a websocket handshake request.
1556This value can only be returned from the following functions:
1557@code{MHD_websocket_check_http_version},
1558@code{MHD_websocket_check_connection_header},
1559@code{MHD_websocket_check_upgrade_header},
1560@code{MHD_websocket_check_version_header},
1561@code{MHD_websocket_create_accept_header}
1562
1563@end table
1564@end deftp
1565
1566
1567@deftp {Enumeration} MHD_WEBSOCKET_CLOSEREASON
1568@cindex websocket
1569Enumeration of possible close reasons for websocket close frames.
1570
1571The possible values are specified in RFC 6455 7.4.1
1572These close reasons here are the default set specified by RFC 6455,
1573but also other close reasons could be used.
1574
1575The definition is for short:
1576@itemize @bullet
1577@item 0-999 are never used (if you pass 0 in
1578@code{MHD_websocket_encode_close} then no close reason is used).
1579@item 1000-2999 are specified by RFC 6455.
1580@item 3000-3999 are specified by libraries, etc. but must be registered by IANA.
1581@item 4000-4999 are reserved for private use.
1582@end itemize
1583
1584Note that websocket streams are only available if you include the header file
1585@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
1586
1587@table @code
1588@item MHD_WEBSOCKET_CLOSEREASON_NO_REASON
1589This value is used as placeholder for @code{MHD_websocket_encode_close}
1590to tell that you don't want to specify any reason.
1591If you use this value then no reason text may be used.
1592This value cannot be a result of decoding, because this value
1593is not a valid close reason for the websocket protocol.
1594
1595@item MHD_WEBSOCKET_CLOSEREASON_REGULAR
1596You close the websocket because it fulfilled its purpose and shall
1597now be closed in a normal, planned way.
1598
1599@item MHD_WEBSOCKET_CLOSEREASON_GOING_AWAY
1600You close the websocket because you are shutting down the server or
1601something similar.
1602
1603@item MHD_WEBSOCKET_CLOSEREASON_PROTOCOL_ERROR
1604You close the websocket because a protocol error occurred
1605during decoding (i. e. invalid byte data).
1606
1607@item MHD_WEBSOCKET_CLOSEREASON_UNSUPPORTED_DATATYPE
1608You close the websocket because you received data which you don't accept.
1609For example if you received a binary frame,
1610but your application only expects text frames.
1611
1612@item MHD_WEBSOCKET_CLOSEREASON_MALFORMED_UTF8
1613You close the websocket because it contains malformed UTF-8.
1614The UTF-8 validity is automatically checked by @code{MHD_websocket_decode},
1615so you don't need to check it on your own.
1616UTF-8 is specified in RFC 3629.
1617
1618@item MHD_WEBSOCKET_CLOSEREASON_POLICY_VIOLATED
1619You close the websocket because you received a frame which is too big
1620to process.
1621You can specify the maximum allowed payload size during the call of
1622@code{MHD_websocket_stream_init} or @code{MHD_websocket_stream_init2}.
1623
1624@item MHD_WEBSOCKET_CLOSEREASON_MISSING_EXTENSION
1625This status code can be sent by the client if it
1626expected a specific extension, but this extension hasn't been negotiated.
1627
1628@item MHD_WEBSOCKET_CLOSEREASON_UNEXPECTED_CONDITION
1629The server closes the websocket because it encountered
1630an unexpected condition that prevented it from fulfilling the request.
1631
1632@end table
1633@end deftp
1634
1635
1636@deftp {Enumeration} MHD_WEBSOCKET_UTF8STEP
1637@cindex websocket
1638Enumeration of possible UTF-8 check steps for websocket functions
1639
1640These values are used during the encoding of fragmented text frames
1641or for error analysis while encoding text frames.
1642Its values specify the next step of the UTF-8 check.
1643UTF-8 sequences consist of one to four bytes.
1644This enumeration just says how long the current UTF-8 sequence is
1645and what is the next expected byte.
1646
1647Note that websocket streams are only available if you include the header file
1648@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
1649
1650@table @code
1651@item MHD_WEBSOCKET_UTF8STEP_NORMAL
1652There is no open UTF-8 sequence.
1653The next byte must be 0x00-0x7F or 0xC2-0xF4.
1654
1655@item MHD_WEBSOCKET_UTF8STEP_UTF2TAIL_1OF1
1656The second byte of a two byte UTF-8 sequence.
1657The first byte was 0xC2-0xDF.
1658The next byte must be 0x80-0xBF.
1659
1660@item MHD_WEBSOCKET_UTF8STEP_UTF3TAIL1_1OF2
1661The second byte of a three byte UTF-8 sequence.
1662The first byte was 0xE0.
1663The next byte must be 0xA0-0xBF.
1664
1665@item MHD_WEBSOCKET_UTF8STEP_UTF3TAIL2_1OF2
1666The second byte of a three byte UTF-8 sequence.
1667The first byte was 0xED.
1668The next byte must by 0x80-0x9F.
1669
1670@item MHD_WEBSOCKET_UTF8STEP_UTF3TAIL_1OF2
1671The second byte of a three byte UTF-8 sequence.
1672The first byte was 0xE1-0xEC or 0xEE-0xEF.
1673The next byte must be 0x80-0xBF.
1674
1675@item MHD_WEBSOCKET_UTF8STEP_UTF3TAIL_2OF2
1676The third byte of a three byte UTF-8 sequence.
1677The next byte must be 0x80-0xBF.
1678
1679@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL1_1OF3
1680The second byte of a four byte UTF-8 sequence.
1681The first byte was 0xF0.
1682The next byte must be 0x90-0xBF.
1683
1684@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL2_1OF3
1685The second byte of a four byte UTF-8 sequence.
1686The first byte was 0xF4.
1687The next byte must be 0x80-0x8F.
1688
1689@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_1OF3
1690The second byte of a four byte UTF-8 sequence.
1691The first byte was 0xF1-0xF3.
1692The next byte must be 0x80-0xBF.
1693
1694@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_2OF3
1695The third byte of a four byte UTF-8 sequence.
1696The next byte must be 0x80-0xBF.
1697
1698@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_3OF3
1699The fourth byte of a four byte UTF-8 sequence.
1700The next byte must be 0x80-0xBF.
1701
1702@end table
1703@end deftp
1704
1705
1706@deftp {Enumeration} MHD_WEBSOCKET_VALIDITY
1707@cindex websocket
1708Enumeration of validity values of a websocket stream
1709
1710These values are used for @code{MHD_websocket_stream_is_valid}
1711and specify the validity status.
1712
1713Note that websocket streams are only available if you include the header file
1714@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
1715
1716@table @code
1717@item MHD_WEBSOCKET_VALIDITY_INVALID
1718The stream is invalid.
1719It cannot be used for decoding anymore.
1720
1721@item MHD_WEBSOCKET_VALIDITY_VALID
1722The stream is valid.
1723Decoding works as expected.
1724
1725@item MHD_WEBSOCKET_VALIDITY_ONLY_VALID_FOR_CONTROL_FRAMES
1726The stream has received a close frame and
1727is partly invalid.
1728You can still use the stream for decoding,
1729but if a data frame is received an error will be reported.
1730After a close frame has been sent, no data frames
1731may follow from the sender of the close frame.
1732
1733@end table
1734@end deftp
1735
1736
1249@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1737@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1250 1738
1251@c ------------------------------------------------------------ 1739@c ------------------------------------------------------------
@@ -1291,6 +1779,12 @@ Information about an MHD daemon.
1291@end deftp 1779@end deftp
1292 1780
1293 1781
1782@deftp {C Struct} MHD_WebSocketStream
1783@cindex websocket
1784Information about a MHD websocket stream.
1785@end deftp
1786
1787
1294@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1788@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1295 1789
1296@c ------------------------------------------------------------ 1790@c ------------------------------------------------------------
@@ -1549,6 +2043,95 @@ iteration.
1549@end deftypefn 2043@end deftypefn
1550 2044
1551 2045
2046@deftypefn {Function Pointer} void* {*MHD_WebSocketMallocCallback} (size_t buf_len)
2047@cindex websocket
2048This callback function is used internally by many websocket functions
2049for allocating data.
2050By default @code{malloc} is used.
2051You can use your own allocation function with @code{MHD_websocket_stream_init2}
2052if you wish to.
2053This can be useful for operating systems like Windows
2054where @code{malloc}, @code{realloc} and @code{free} are compiler-dependent.
2055You can call the associated @code{malloc} callback of
2056a websocket stream with @code{MHD_websocket_malloc}.
2057
2058@table @var
2059@item buf_len
2060size of the buffer to allocate in bytes.
2061@end table
2062
2063Return the pointer of the allocated buffer or @code{NULL} on failure.
2064@end deftypefn
2065
2066
2067@deftypefn {Function Pointer} void* {*MHD_WebSocketReallocCallback} (void *buf, size_t new_buf_len)
2068@cindex websocket
2069This callback function is used internally by many websocket
2070functions for reallocating data.
2071By default @code{realloc} is used.
2072You can use your own reallocation function with
2073@code{MHD_websocket_stream_init2} if you wish to.
2074This can be useful for operating systems like Windows
2075where @code{malloc}, @code{realloc} and @code{free} are compiler-dependent.
2076You can call the associated @code{realloc} callback of
2077a websocket stream with @code{MHD_websocket_realloc}.
2078
2079@table @var
2080@item buf
2081current buffer, may be @code{NULL};
2082
2083@item new_buf_len
2084new size of the buffer in bytes.
2085@end table
2086
2087Return the pointer of the reallocated buffer or @code{NULL} on failure.
2088On failure the old pointer must remain valid.
2089@end deftypefn
2090
2091
2092@deftypefn {Function Pointer} void {*MHD_WebSocketFreeCallback} (void *buf)
2093@cindex websocket
2094This callback function is used internally by many websocket
2095functions for freeing data.
2096By default @code{free} is used.
2097You can use your own free function with
2098@code{MHD_websocket_stream_init2} if you wish to.
2099This can be useful for operating systems like Windows
2100where @code{malloc}, @code{realloc} and @code{free} are compiler-dependent.
2101You can call the associated @code{free} callback of
2102a websocket stream with @code{MHD_websocket_free}.
2103
2104@table @var
2105@item cls
2106current buffer to free, this may be @code{NULL} then nothing happens.
2107@end table
2108@end deftypefn
2109
2110
2111@deftypefn {Function Pointer} size_t {*MHD_WebSocketRandomNumberGenerator} (void *cls, void* buf, size_t buf_len)
2112@cindex websocket
2113This callback function is used for generating random numbers
2114for masking payload data in client mode.
2115If you use websockets in server mode with @emph{libmicrohttpd} then
2116you don't need a random number generator, because
2117the server doesn't mask its outgoing messages.
2118However if you wish to use a websocket stream in client mode,
2119you must pass this callback function to @code{MHD_websocket_stream_init2}.
2120
2121@table @var
2122@item cls
2123closure specified in @code{MHD_websocket_stream_init2};
2124@item buf
2125buffer to fill with random values;
2126@item buf_len
2127size of buffer in bytes.
2128@end table
2129
2130Return the number of generated random bytes.
2131The return value should usually equal to buf_len.
2132@end deftypefn
2133
2134
1552@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2135@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1553 2136
1554@c ------------------------------------------------------------ 2137@c ------------------------------------------------------------
@@ -3346,6 +3929,704 @@ shorter afterwards due to elimination of escape sequences).
3346 3929
3347 3930
3348 3931
3932
3933@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3934
3935@c ------------------------------------------------------------
3936@node microhttpd-websocket
3937@chapter Websocket functions.
3938
3939@noindent
3940Websocket functions provide what you need to use an upgraded connection
3941as a websocket.
3942These functions are only available if you include the header file
3943@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
3944
3945@menu
3946* microhttpd-websocket handshake:: Websocket handshake functions
3947* microhttpd-websocket stream:: Websocket stream functions
3948* microhttpd-websocket decode:: Websocket decode functions
3949* microhttpd-websocket encode:: Websocket encode functions
3950* microhttpd-websocket memory:: Websocket memory functions
3951@end menu
3952
3953@c ------------------------------------------------------------
3954@node microhttpd-websocket handshake
3955@section Websocket handshake functions
3956
3957
3958@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_check_http_version (const char* http_version)
3959@cindex websocket
3960Checks the HTTP version of the incoming request.
3961Websocket requests are only allowed for HTTP/1.1 or above.
3962
3963@table @var
3964@item http_version
3965The value of the @code{version} parameter of your
3966@code{access_handler} callback.
3967If you pass @code{NULL} then this is handled like a not
3968matching HTTP version.
3969@end table
3970
3971Returns 0 when the HTTP version is
3972valid for a websocket request and
3973a value less than zero when the HTTP version isn't
3974valid for a websocket request.
3975Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
3976@end deftypefun
3977
3978
3979@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_check_connection_header (const char* connection_header)
3980@cindex websocket
3981Checks the value of the @code{Connection} HTTP request header.
3982Websocket requests require the token @code{Upgrade} in
3983the @code{Connection} HTTP request header.
3984
3985@table @var
3986@item connection_header
3987Value of the @code{Connection} request header.
3988You can get this request header value by passing
3989@code{MHD_HTTP_HEADER_CONNECTION} to
3990@code{MHD_lookup_connection_value()}.
3991If you pass @code{NULL} then this is handled like a not
3992matching @code{Connection} header value.
3993@end table
3994
3995Returns 0 when the @code{Connection} header is
3996valid for a websocket request and
3997a value less than zero when the @code{Connection} header isn't
3998valid for a websocket request.
3999Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4000@end deftypefun
4001
4002
4003@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_check_upgrade_header (const char* upgrade_header)
4004@cindex websocket
4005Checks the value of the @code{Upgrade} HTTP request header.
4006Websocket requests require the value @code{websocket} in
4007the @code{Upgrade} HTTP request header.
4008
4009@table @var
4010@item upgrade_header
4011Value of the @code{Upgrade} request header.
4012You can get this request header value by passing
4013@code{MHD_HTTP_HEADER_UPGRADE} to
4014@code{MHD_lookup_connection_value()}.
4015If you pass @code{NULL} then this is handled like a not
4016matching @code{Upgrade} header value.
4017@end table
4018
4019Returns 0 when the @code{Upgrade} header is
4020valid for a websocket request and
4021a value less than zero when the @code{Upgrade} header isn't
4022valid for a websocket request.
4023Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4024@end deftypefun
4025
4026
4027@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_check_version_header (const char* version_header)
4028@cindex websocket
4029Checks the value of the @code{Sec-WebSocket-Version} HTTP request header.
4030Websocket requests require the value @code{13} in
4031the @code{Sec-WebSocket-Version} HTTP request header.
4032
4033@table @var
4034@item version_header
4035Value of the @code{Sec-WebSocket-Version} request header.
4036You can get this request header value by passing
4037@code{MHD_HTTP_HEADER_SEC_WEBSOCKET_VERSION} to
4038@code{MHD_lookup_connection_value()}.
4039If you pass @code{NULL} then this is handled like a not
4040matching @code{Sec-WebSocket-Version} header value.
4041@end table
4042
4043Returns 0 when the @code{Sec-WebSocket-Version} header is
4044valid for a websocket request and
4045a value less than zero when the @code{Sec-WebSocket-Version} header isn't
4046valid for a websocket request.
4047Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4048@end deftypefun
4049
4050
4051@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_create_accept_header (const char* sec_websocket_key, char* sec_websocket_accept)
4052@cindex websocket
4053Checks the value of the @code{Sec-WebSocket-Key}
4054HTTP request header and generates the value for
4055the @code{Sec-WebSocket-Accept} HTTP response header.
4056The generated value must be sent to the client.
4057
4058@table @var
4059@item sec_websocket_key
4060Value of the @code{Sec-WebSocket-Key} request header.
4061You can get this request header value by passing
4062@code{MHD_HTTP_HEADER_SEC_WEBSOCKET_KEY} to
4063@code{MHD_lookup_connection_value()}.
4064If you pass @code{NULL} then this is handled like a not
4065matching @code{Sec-WebSocket-Key} header value.
4066
4067@item sec_websocket_accept
4068Response buffer, which will receive
4069the generated value for the @code{Sec-WebSocket-Accept}
4070HTTP response header.
4071This buffer must be at least 29 bytes long and
4072will contain the response value plus a terminating @code{NUL}
4073character on success.
4074Must not be @code{NULL}.
4075You can add this HTTP header to your response by passing
4076@code{MHD_HTTP_HEADER_SEC_WEBSOCKET_ACCEPT} to
4077@code{MHD_add_response_header()}.
4078@end table
4079
4080Returns 0 when the @code{Sec-WebSocket-Key} header was
4081not empty and a result value for the @code{Sec-WebSocket-Accept}
4082was calculated.
4083A value less than zero is returned when the @code{Sec-WebSocket-Key}
4084header isn't valid for a websocket request or when any
4085error occurred.
4086Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4087@end deftypefun
4088
4089
4090@c ------------------------------------------------------------
4091@node microhttpd-websocket stream
4092@section Websocket stream functions
4093
4094@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_stream_init (struct MHD_WebSocketStream **ws, int flags, size_t max_payload_size)
4095@cindex websocket
4096Creates a new websocket stream, used for decoding/encoding.
4097
4098@table @var
4099@item ws
4100pointer a variable to fill with the newly created
4101@code{struct MHD_WebSocketStream},
4102receives @code{NULL} on error. May not be @code{NULL}.
4103
4104If not required anymore, free the created websocket stream with
4105@code{MHD_websocket_stream_free()}.
4106
4107@item flags
4108combination of @code{enum MHD_WEBSOCKET_FLAG} values to
4109modify the behavior of the websocket stream.
4110
4111@item max_payload_size
4112maximum size for incoming payload data in bytes. Use 0 to allow each size.
4113@end table
4114
4115Returns 0 on success, negative values on error.
4116Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4117@end deftypefun
4118
4119
4120@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_stream_init2 (struct MHD_WebSocketStream **ws, int flags, size_t max_payload_size, MHD_WebSocketMallocCallback callback_malloc, MHD_WebSocketReallocCallback callback_realloc, MHD_WebSocketFreeCallback callback_free, void* cls_rng, MHD_WebSocketRandomNumberGenerator callback_rng)
4121@cindex websocket
4122Creates a new websocket stream, used for decoding/encoding,
4123but with custom memory functions for malloc, realloc and free.
4124Also a random number generator can be specified for client mode.
4125
4126@table @var
4127@item ws
4128pointer a variable to fill with the newly created
4129@code{struct MHD_WebSocketStream},
4130receives @code{NULL} on error. Must not be @code{NULL}.
4131
4132If not required anymore, free the created websocket stream with
4133@code{MHD_websocket_stream_free}.
4134
4135@item flags
4136combination of @code{enum MHD_WEBSOCKET_FLAG} values to
4137modify the behavior of the websocket stream.
4138
4139@item max_payload_size
4140maximum size for incoming payload data in bytes. Use 0 to allow each size.
4141
4142@item callback_malloc
4143callback function for allocating memory. Must not be @code{NULL}.
4144The shorter @code{MHD_websocket_stream_init()} passes a reference to @code{malloc} here.
4145
4146@item callback_realloc
4147callback function for reallocating memory. Must not be @code{NULL}.
4148The shorter @code{MHD_websocket_stream_init()} passes a reference to @code{realloc} here.
4149
4150@item callback_free
4151callback function for freeing memory. Must not be @code{NULL}.
4152The shorter @code{MHD_websocket_stream_init()} passes a reference to @code{free} here.
4153
4154@item cls_rng
4155closure for the random number generator.
4156This is only required when
4157@code{MHD_WEBSOCKET_FLAG_CLIENT} is passed in @code{flags}.
4158The given value is passed to the random number generator callback.
4159May be @code{NULL} if not needed.
4160Should be @code{NULL} when you are not using @code{MHD_WEBSOCKET_FLAG_CLIENT}.
4161The shorter @code{MHD_websocket_stream_init} passes @code{NULL} here.
4162
4163@item callback_rng
4164callback function for a secure random number generator.
4165This is only required when @code{MHD_WEBSOCKET_FLAG_CLIENT} is
4166passed in @code{flags} and must not be @code{NULL} then.
4167Should be @code{NULL} otherwise.
4168The shorter @code{MHD_websocket_stream_init()} passes @code{NULL} here.
4169@end table
4170
4171Returns 0 on success, negative values on error.
4172Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4173@end deftypefun
4174
4175
4176@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_stream_free (struct MHD_WebSocketStream *ws)
4177@cindex websocket
4178Frees a previously allocated websocket stream
4179
4180@table @var
4181@item ws
4182websocket stream to free, this value may be @code{NULL}.
4183@end table
4184
4185Returns 0 on success, negative values on error.
4186Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4187@end deftypefun
4188
4189
4190@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_stream_invalidate (struct MHD_WebSocketStream *ws)
4191@cindex websocket
4192Invalidates a websocket stream.
4193After invalidation a websocket stream cannot be used for decoding anymore.
4194Encoding is still possible.
4195
4196@table @var
4197@item ws
4198websocket stream to invalidate.
4199@end table
4200
4201Returns 0 on success, negative values on error.
4202Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4203@end deftypefun
4204
4205
4206@deftypefun {enum MHD_WEBSOCKET_VALIDITY} MHD_websocket_stream_is_valid (struct MHD_WebSocketStream *ws)
4207@cindex websocket
4208Queries whether a websocket stream is valid.
4209Invalidated websocket streams cannot be used for decoding anymore.
4210Encoding is still possible.
4211
4212@table @var
4213@item ws
4214websocket stream to invalidate.
4215@end table
4216
4217Returns 0 if invalid, 1 if valid for all types or
42182 if valid only for control frames.
4219Can be compared with @code{enum MHD_WEBSOCKET_VALIDITY}.
4220@end deftypefun
4221
4222
4223@c ------------------------------------------------------------
4224@node microhttpd-websocket decode
4225@section Websocket decode functions
4226
4227
4228@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_decode (struct MHD_WebSocketStream* ws, const char* streambuf, size_t streambuf_len, size_t* streambuf_read_len, char** payload, size_t* payload_len)
4229@cindex websocket
4230Decodes a byte sequence for a websocket stream.
4231Decoding is done until either a frame is complete or
4232the end of the byte sequence is reached.
4233
4234@table @var
4235@item ws
4236websocket stream for decoding.
4237
4238@item streambuf
4239byte sequence for decoding.
4240This is what you typically received via @code{recv()}.
4241
4242@item streambuf_len
4243length of the byte sequence in parameter @code{streambuf}.
4244
4245@item streambuf_read_len
4246pointer to a variable, which receives the number of bytes,
4247that has been processed by this call.
4248This value may be less than the value of @code{streambuf_len} when
4249a frame is decoded before the end of the buffer is reached.
4250The remaining bytes of @code{buf} must be passed to
4251the next call of this function.
4252
4253@item payload
4254pointer to a variable, which receives the allocated buffer with the payload
4255data of the decoded frame. Must not be @code{NULL}.
4256If no decoded data is available or an error occurred @code{NULL} is returned.
4257When the returned value is not @code{NULL} then the buffer contains always
4258@code{payload_len} bytes plus one terminating @code{NUL} character
4259(regardless of the frame type).
4260
4261The caller must free this buffer using @code{MHD_websocket_free()}.
4262
4263If you passed the flag @code{MHD_WEBSOCKET_FLAG_GENERATE_CLOSE_FRAMES_ON_ERROR}
4264upon creation of the websocket stream and a decoding error occurred
4265(function return value less than 0), then this buffer contains
4266a generated close frame, which must be sent via the socket to the recipient.
4267
4268If you passed the flag @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
4269upon creation of the websocket stream then
4270this payload may only be a part of the complete message.
4271Only complete UTF-8 sequences are returned for fragmented text frames.
4272If necessary the UTF-8 sequence will be completed with the next text fragment.
4273
4274@item payload_len
4275pointer to a variable, which receives length of the result
4276@code{payload} buffer in bytes.
4277Must not be @code{NULL}.
4278This receives 0 when no data is available, when the decoded payload
4279has a length of zero or when an error occurred.
4280@end table
4281
4282Returns a value greater than zero when a frame is complete.
4283Compare with @code{enum MHD_WEBSOCKET_STATUS} to distinguish the frame type.
4284Returns 0 when the call succeeded, but no frame is available.
4285Returns a value less than zero on errors.
4286@end deftypefun
4287
4288
4289@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_split_close_reason (const char* payload, size_t payload_len, unsigned short* reason_code, const char** reason_utf8, size_t* reason_utf8_len)
4290@cindex websocket
4291Splits the payload of a decoded close frame.
4292
4293@table @var
4294@item payload
4295payload of the close frame.
4296This parameter may only be @code{NULL} if @code{payload_len} is 0.
4297
4298@item payload_len
4299length of @code{payload}.
4300
4301@item reason_code
4302pointer to a variable, which receives the numeric close reason.
4303If there was no close reason, this is 0.
4304This value can be compared with @code{enum MHD_WEBSOCKET_CLOSEREASON}.
4305May be @code{NULL}.
4306
4307@item reason_utf8
4308pointer to a variable, which receives the literal close reason.
4309If there was no literal close reason, this will be @code{NULL}.
4310May be @code{NULL}.
4311
4312Please note that no memory is allocated in this function.
4313If not @code{NULL} the returned value of this parameter
4314points to a position in the specified @code{payload}.
4315
4316@item reason_utf8_len
4317pointer to a variable, which receives the length of the literal close reason.
4318If there was no literal close reason, this is 0.
4319May be @code{NULL}.
4320@end table
4321
4322Returns 0 on success or a value less than zero on errors.
4323Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4324@end deftypefun
4325
4326
4327@c ------------------------------------------------------------
4328@node microhttpd-websocket encode
4329@section Websocket encode functions
4330
4331
4332@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_encode_text (struct MHD_WebSocketStream* ws, const char* payload_utf8, size_t payload_utf8_len, int fragmentation, char** frame, size_t* frame_len, int* utf8_step)
4333@cindex websocket
4334Encodes an UTF-8 encoded text into websocket text frame
4335
4336@table @var
4337@item ws
4338websocket stream;
4339
4340@item payload_utf8
4341text to send. This must be UTF-8 encoded.
4342If you don't want UTF-8 then send a binary frame
4343with @code{MHD_websocket_encode_binary()} instead.
4344May be be @code{NULL} if @code{payload_utf8_len} is 0,
4345must not be @code{NULL} otherwise.
4346
4347@item payload_utf8_len
4348length of @code{payload_utf8} in bytes.
4349
4350@item fragmentation
4351A value of @code{enum MHD_WEBSOCKET_FRAGMENTATION}
4352to specify the fragmentation behavior.
4353Specify @code{MHD_WEBSOCKET_FRAGMENTATION_NONE} or just 0
4354if you don't want to use fragmentation (default).
4355
4356@item frame
4357pointer to a variable, which receives a buffer with the encoded text frame.
4358Must not be @code{NULL}.
4359The buffer contains what you typically send via @code{send()} to the recipient.
4360If no encoded data is available the variable receives @code{NULL}.
4361
4362If the variable is not @code{NULL} then the buffer contains always
4363@code{frame_len} bytes plus one terminating @code{NUL} character.
4364The caller must free this buffer using @code{MHD_websocket_free()}.
4365
4366@item frame_len
4367pointer to a variable, which receives the length of the encoded frame in bytes.
4368Must not be @code{NULL}.
4369
4370@item utf8_step
4371If fragmentation is used (the parameter @code{fragmentation} is not 0)
4372then is parameter is required and must not be @code{NULL}.
4373If no fragmentation is used, this parameter is optional and
4374should be @code{NULL}.
4375
4376This parameter is a pointer to a variable which contains the last check status
4377of the UTF-8 sequence. It is required to continue a previous
4378UTF-8 sequence check when fragmentation is used, because a UTF-8 sequence
4379could be splitted upon fragments.
4380
4381@code{enum MHD_WEBSOCKET_UTF8STEP} is used for this value.
4382If you start a new fragment using
4383@code{MHD_WEBSOCKET_FRAGMENTATION_NONE} or
4384@code{MHD_WEBSOCKET_FRAGMENTATION_FIRST} the old value of this variable
4385will be discarded and the value of this variable will be initialized
4386to @code{MHD_WEBSOCKET_UTF8STEP_NORMAL}.
4387On all other fragmentation modes the previous value of the pointed variable
4388will be used to continue the UTF-8 sequence check.
4389@end table
4390
4391Returns 0 on success or a value less than zero on errors.
4392Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4393@end deftypefun
4394
4395
4396@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_encode_binary (struct MHD_WebSocketStream* ws, const char* payload, size_t payload_len, int fragmentation, char** frame, size_t* frame_len)
4397@cindex websocket
4398Encodes binary data into websocket binary frame
4399
4400@table @var
4401@item ws
4402websocket stream;
4403
4404@item payload
4405binary data to send.
4406May be be @code{NULL} if @code{payload_len} is 0,
4407must not be @code{NULL} otherwise.
4408
4409@item payload_len
4410length of @code{payload} in bytes.
4411
4412@item fragmentation
4413A value of @code{enum MHD_WEBSOCKET_FRAGMENTATION}
4414to specify the fragmentation behavior.
4415Specify @code{MHD_WEBSOCKET_FRAGMENTATION_NONE} or just 0
4416if you don't want to use fragmentation (default).
4417
4418@item frame
4419pointer to a variable, which receives a buffer with the encoded binary frame.
4420Must not be @code{NULL}.
4421The buffer contains what you typically send via @code{send()} to the recipient.
4422If no encoded data is available the variable receives @code{NULL}.
4423
4424If the variable is not @code{NULL} then the buffer contains always
4425@code{frame_len} bytes plus one terminating @code{NUL} character.
4426The caller must free this buffer using @code{MHD_websocket_free()}.
4427
4428@item frame_len
4429pointer to a variable, which receives the length of the encoded frame in bytes.
4430Must not be @code{NULL}.
4431@end table
4432
4433Returns 0 on success or a value less than zero on errors.
4434Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4435@end deftypefun
4436
4437
4438@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_encode_ping (struct MHD_WebSocketStream* ws, const char* payload, size_t payload_len, char** frame, size_t* frame_len)
4439@cindex websocket
4440Encodes a websocket ping frame.
4441Ping frames are used to check whether a recipient is still available
4442and what latency the websocket connection has.
4443
4444@table @var
4445@item ws
4446websocket stream;
4447
4448@item payload
4449binary ping data to send.
4450May be @code{NULL} if @code{payload_len} is 0.
4451
4452@item payload_len
4453length of @code{payload} in bytes.
4454This may not exceed 125 bytes.
4455
4456@item frame
4457pointer to a variable, which receives a buffer with the encoded ping frame.
4458Must not be @code{NULL}.
4459The buffer contains what you typically send via @code{send()} to the recipient.
4460If no encoded data is available the variable receives @code{NULL}.
4461
4462If the variable is not @code{NULL} then the buffer contains always
4463@code{frame_len} bytes plus one terminating @code{NUL} character.
4464The caller must free this buffer using @code{MHD_websocket_free()}.
4465
4466@item frame_len
4467pointer to a variable, which receives the length of the encoded frame in bytes.
4468Must not be @code{NULL}.
4469@end table
4470
4471Returns 0 on success or a value less than zero on errors.
4472Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4473@end deftypefun
4474
4475
4476@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_encode_pong (struct MHD_WebSocketStream* ws, const char* payload, size_t payload_len, char** frame, size_t* frame_len)
4477@cindex websocket
4478Encodes a websocket pong frame.
4479Pong frames are used to answer a previously received websocket ping frame.
4480
4481@table @var
4482@item ws
4483websocket stream;
4484
4485@item payload
4486binary pong data to send, which should be
4487the decoded payload from the received ping frame.
4488May be @code{NULL} if @code{payload_len} is 0.
4489
4490@item payload_len
4491length of @code{payload} in bytes.
4492This may not exceed 125 bytes.
4493
4494@item frame
4495pointer to a variable, which receives a buffer with the encoded pong frame.
4496Must not be @code{NULL}.
4497The buffer contains what you typically send via @code{send()} to the recipient.
4498If no encoded data is available the variable receives @code{NULL}.
4499
4500If the variable is not @code{NULL} then the buffer contains always
4501@code{frame_len} bytes plus one terminating @code{NUL} character.
4502The caller must free this buffer using @code{MHD_websocket_free()}.
4503
4504@item frame_len
4505pointer to a variable, which receives the length of the encoded frame in bytes.
4506Must not be @code{NULL}.
4507@end table
4508
4509Returns 0 on success or a value less than zero on errors.
4510Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4511@end deftypefun
4512
4513
4514@deftypefun {enum MHD_WEBSOCKET_STATUS} MHD_websocket_encode_close (struct MHD_WebSocketStream* ws, unsigned short reason_code, const char* reason_utf8, size_t reason_utf8_len, char** frame, size_t* frame_len)
4515@cindex websocket
4516Encodes a websocket close frame.
4517Close frames are used to close a websocket connection in a formal way.
4518
4519@table @var
4520@item ws
4521websocket stream;
4522
4523@item reason_code
4524reason for close.
4525You can use @code{enum MHD_WEBSOCKET_CLOSEREASON} for typical reasons,
4526but you are not limited to these values.
4527The allowed values are specified in RFC 6455 7.4.
4528If you don't want to enter a reason, you can specify
4529@code{MHD_WEBSOCKET_CLOSEREASON_NO_REASON} (or just 0) then
4530no reason is encoded.
4531
4532@item reason_utf8
4533An UTF-8 encoded text reason why the connection is closed.
4534This may be @code{NULL} if @code{reason_utf8_len} is 0.
4535This must be @code{NULL} if @code{reason_code} equals to zero
4536(@code{MHD_WEBSOCKET_CLOSEREASON_NO_REASON}).
4537
4538@item reason_utf8_len
4539length of the UTF-8 encoded text reason in bytes.
4540This may not exceed 123 bytes.
4541
4542@item frame
4543pointer to a variable, which receives a buffer with the encoded close frame.
4544Must not be @code{NULL}.
4545The buffer contains what you typically send via @code{send()} to the recipient.
4546If no encoded data is available the variable receives @code{NULL}.
4547
4548If the variable is not @code{NULL} then the buffer contains always
4549@code{frame_len} bytes plus one terminating @code{NUL} character.
4550The caller must free this buffer using @code{MHD_websocket_free()}.
4551
4552@item frame_len
4553pointer to a variable, which receives the length of the encoded frame in bytes.
4554Must not be @code{NULL}.
4555@end table
4556
4557Returns 0 on success or a value less than zero on errors.
4558Can be compared with @code{enum MHD_WEBSOCKET_STATUS}.
4559@end deftypefun
4560
4561
4562@c ------------------------------------------------------------
4563@node microhttpd-websocket memory
4564@section Websocket memory functions
4565
4566
4567@deftypefun {void*} MHD_websocket_malloc (struct MHD_WebSocketStream* ws, size_t buf_len)
4568@cindex websocket
4569Allocates memory with the associated @code{malloc()} function
4570of the websocket stream.
4571The memory allocation function could be different for a websocket stream if
4572@code{MHD_websocket_stream_init2()} has been used for initialization.
4573
4574@table @var
4575@item ws
4576websocket stream;
4577
4578@item buf_len
4579size of the buffer to allocate in bytes.
4580@end table
4581
4582Returns the pointer of the allocated buffer or @code{NULL} on failure.
4583@end deftypefun
4584
4585
4586@deftypefun {void*} MHD_websocket_realloc (struct MHD_WebSocketStream* ws, void* buf, size_t new_buf_len)
4587@cindex websocket
4588Reallocates memory with the associated @code{realloc()} function
4589of the websocket stream.
4590The memory reallocation function could be different for a websocket stream if
4591@code{MHD_websocket_stream_init2()} has been used for initialization.
4592
4593@table @var
4594@item ws
4595websocket stream;
4596
4597@item buf
4598current buffer, may be @code{NULL};
4599
4600@item new_buf_len
4601new size of the buffer in bytes.
4602@end table
4603
4604Return the pointer of the reallocated buffer or @code{NULL} on failure.
4605On failure the old pointer remains valid.
4606@end deftypefun
4607
4608
4609@deftypefun {void} MHD_websocket_free (struct MHD_WebSocketStream* ws, void* buf)
4610@cindex websocket
4611Frees memory with the associated @code{free()} function
4612of the websocket stream.
4613The memory free function could be different for a websocket stream if
4614@code{MHD_websocket_stream_init2()} has been used for initialization.
4615
4616@table @var
4617@item ws
4618websocket stream;
4619
4620@item buf
4621buffer to free, this may be @code{NULL} then nothing happens.
4622@end table
4623
4624@end deftypefun
4625
4626
4627
4628
4629
3349@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 4630@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3350 4631
3351 4632