1<class name = "zframe" 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    working with single message frames
12
13    <constant name = "more" value = "1" />
14    <constant name = "reuse" value = "2" />
15    <constant name = "dontwait" value = "4" />
16
17    <constructor>
18        Create a new frame. If size is not null, allocates the frame data
19        to the specified size. If additionally, data is not null, copies
20        size octets from the specified data into the frame body.
21        <argument name = "data" type = "buffer" c_type = "const void *" />
22        <argument name = "size" type = "size" />
23    </constructor>
24
25    <destructor>
26        Destroy a frame
27    </destructor>
28
29    <constructor name = "new empty">
30        Create an empty (zero-sized) frame
31    </constructor>
32
33    <constructor name = "from">
34        Create a frame with a specified string content.
35        <argument name = "string" type = "string" />
36    </constructor>
37
38    <constructor name = "recv">
39        Receive frame from socket, returns zframe_t object or NULL if the recv
40        was interrupted. Does a blocking recv, if you want to not block then use
41        zpoller or zloop.
42        <argument name = "source" type = "sockish" />
43    </constructor>
44
45    <method name = "send" singleton = "1">
46        Send a frame to a socket, destroy frame after sending.
47        Return -1 on error, 0 on success.
48        <argument name = "self_p" type = "zframe" by_reference = "1" />
49        <argument name = "dest" type = "sockish" />
50        <argument name = "flags" type = "integer" />
51        <return type = "integer" />
52    </method>
53
54    <method name = "size">
55        Return number of bytes in frame data
56        <return type = "size" />
57    </method>
58
59    <method name = "data">
60        Return address of frame data
61        <return type = "buffer" mutable = "1" size = ".size" />
62    </method>
63
64    <method name = "meta">
65        Return meta data property for frame
66        The caller shall not modify or free the returned value, which shall be
67        owned by the message.
68        <argument name = "property" type = "string" />
69        <return type = "string" fresh = "0" />
70    </method>
71
72    <method name = "dup">
73        Create a new frame that duplicates an existing frame. If frame is null,
74        or memory was exhausted, returns null.
75        <return type = "zframe" fresh = "1" />
76    </method>
77
78    <method name = "strhex">
79        Return frame data encoded as printable hex string, useful for 0MQ UUIDs.
80        Caller must free string when finished with it.
81        <return type = "string" fresh = "1" />
82    </method>
83
84    <method name = "strdup">
85        Return frame data copied into freshly allocated string
86        Caller must free string when finished with it.
87        <return type = "string" fresh = "1" />
88    </method>
89
90    <method name = "streq">
91        Return TRUE if frame body is equal to string, excluding terminator
92        <argument name = "string" type = "string" />
93        <return type = "boolean" />
94    </method>
95
96    <method name = "more">
97        Return frame MORE indicator (1 or 0), set when reading frame from socket
98        or by the zframe_set_more() method
99        <return type = "integer" />
100    </method>
101
102    <method name = "set more">
103        Set frame MORE indicator (1 or 0). Note this is NOT used when sending
104        frame to socket, you have to specify flag explicitly.
105        <argument name = "more" type = "integer" />
106    </method>
107
108    <method name = "routing id" state = "draft" >
109        Return frame routing ID, if the frame came from a ZMQ_SERVER socket.
110        Else returns zero.
111        <return type = "number" size = "4" />
112    </method>
113
114    <method name = "set routing id" state = "draft" >
115        Set routing ID on frame. This is used if/when the frame is sent to a
116        ZMQ_SERVER socket.
117        <argument name = "routing id" type = "number" size = "4" />
118    </method>
119
120    <method name = "group" state = "draft" >
121        Return frame group of radio-dish pattern.
122        <return type = "string" />
123    </method>
124
125    <method name = "set group" state = "draft" >
126        Set group on frame. This is used if/when the frame is sent to a
127        ZMQ_RADIO socket.
128        Return -1 on error, 0 on success.
129        <argument name = "group" type = "string" />
130        <return type = "integer" />
131    </method>
132
133    <method name = "eq">
134        Return TRUE if two frames have identical size and data
135        If either frame is NULL, equality is always false.
136        <argument name = "other" type = "zframe" />
137        <return type = "boolean" />
138    </method>
139
140    <method name = "reset">
141        Set new contents for frame
142        <argument name = "data" type = "buffer" c_type = "const void *" />
143        <argument name = "size" type = "size" />
144    </method>
145
146    <method name = "print">
147        Send message to zsys log sink (may be stdout, or system facility as
148        configured by zsys_set_logstream). Prefix shows before frame, if not null.
149        <argument name = "prefix" type = "string" />
150    </method>
151
152    <method name = "is" singleton = "1">
153        Probe the supplied object, and report if it looks like a zframe_t.
154        <argument name = "self" type = "anything" />
155        <return type = "boolean" />
156    </method>
157</class>
158