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