1<class name = "zstr" state = "stable">
2    <!--
3    Copyright (c) the Contributors as noted in the AUTHORS file.
4    This file is part of CZMQ, the high-level C binding for 0MQ:
5    http://czmq.zeromq.org.
6
7    This Source Code Form is subject to the terms of the Mozilla Public
8    License, v. 2.0. If a copy of the MPL was not distributed with this
9    file, You can obtain one at http://mozilla.org/MPL/2.0/.
10    -->
11    sending and receiving strings
12
13    <method name = "recv" singleton = "1">
14        Receive C string from socket. Caller must free returned string using
15        zstr_free(). Returns NULL if the context is being terminated or the
16        process was interrupted.
17        <argument name = "source" type = "sockish" />
18        <return type = "string" fresh = "1" />
19    </method>
20
21    <method name = "recvx" singleton = "1">
22        Receive a series of strings (until NULL) from multipart data.
23        Each string is allocated and filled with string data; if there
24        are not enough frames, unallocated strings are set to NULL.
25        Returns -1 if the message could not be read, else returns the
26        number of strings filled, zero or more. Free each returned string
27        using zstr_free(). If not enough strings are provided, remaining
28        multipart frames in the message are dropped.
29        <argument name = "source" type = "sockish" />
30        <argument name = "string_p" type = "string" by_reference = "1" variadic = "1" />
31        <return type = "integer" />
32    </method>
33
34    <method name = "recv compress" singleton = "1" state = "draft">
35        De-compress and receive C string from socket, received as a message
36        with two frames: size of the uncompressed string, and the string itself.
37        Caller must free returned string using zstr_free(). Returns NULL if the
38        context is being terminated or the process was interrupted.
39        <argument name = "source" type = "sockish" />
40        <return type = "string" fresh = "1" />
41    </method>
42
43    <method name = "send" singleton = "1">
44        Send a C string to a socket, as a frame. The string is sent without
45        trailing null byte; to read this you can use zstr_recv, or a similar
46        method that adds a null terminator on the received string. String
47        may be NULL, which is sent as "".
48        <argument name = "dest" type = "sockish" />
49        <argument name = "string" type = "string" />
50        <return type = "integer" />
51    </method>
52
53    <method name = "sendm" singleton = "1">
54        Send a C string to a socket, as zstr_send(), with a MORE flag, so that
55        you can send further strings in the same multi-part message.
56        <argument name = "dest" type = "sockish" />
57        <argument name = "string" type = "string" />
58        <return type = "integer" />
59    </method>
60
61    <method name = "sendf" singleton = "1">
62        Send a formatted string to a socket. Note that you should NOT use
63        user-supplied strings in the format (they may contain '%' which
64        will create security holes).
65        <argument name = "dest" type = "sockish" />
66        <argument name = "format" type = "format" />
67        <return type = "integer" />
68    </method>
69
70    <method  name = "sendfm" singleton = "1">
71        Send a formatted string to a socket, as for zstr_sendf(), with a
72        MORE flag, so that you can send further strings in the same multi-part
73        message.
74        <argument name = "dest" type = "sockish" />
75        <argument name = "format" type = "format" />
76        <return type = "integer" />
77    </method>
78
79    <method name = "sendx" singleton = "1">
80        Send a series of strings (until NULL) as multipart data
81        Returns 0 if the strings could be sent OK, or -1 on error.
82        <argument name = "dest" type = "sockish" />
83        <argument name = "string" type = "string" variadic = "1" />
84        <return type = "integer" />
85    </method>
86
87    <method name = "send compress" singleton = "1" state = "draft">
88        Compress and send a C string to a socket, as a message with two frames:
89        size of the uncompressed string, and the string itself. The string is
90        sent without trailing null byte; to read this you can use
91        zstr_recv_compress, or a similar method that de-compresses and adds a
92        null terminator on the received string.
93        <argument name = "dest" type = "sockish" />
94        <argument name = "string" type = "string" />
95        <return type = "integer" />
96    </method>
97
98    <method name = "sendm compress" singleton = "1" state = "draft">
99        Compress and send a C string to a socket, as zstr_send_compress(),
100        with a MORE flag, so that you can send further strings in the same
101        multi-part message.
102        <argument name = "dest" type = "sockish" />
103        <argument name = "string" type = "string" />
104        <return type = "integer" />
105    </method>
106
107    <method name = "str" singleton = "1" state = "draft" >
108        Accepts a void pointer and returns a fresh character string. If source
109        is null, returns an empty string.
110        <argument name = "source" type = "sockish" />
111        <return type = "string" fresh = "1" />
112    </method>
113
114    <method name = "free" singleton = "1">
115        Free a provided string, and nullify the parent pointer. Safe to call on
116        a null pointer.
117        <argument name = "string_p" type = "string" by_reference = "1" />
118    </method>
119</class>
120