1################################################################################ 2# THIS FILE IS 100% GENERATED BY ZPROJECT; DO NOT EDIT EXCEPT EXPERIMENTALLY # 3# Read the zproject/README.md for information about making permanent changes. # 4################################################################################ 5 6module CZMQ 7 module FFI 8 9 # working with multipart messages 10 # @note This class is 100% generated using zproject. 11 class Zmsg 12 # Raised when one tries to use an instance of {Zmsg} after 13 # the internal pointer to the native object has been nullified. 14 class DestroyedError < RuntimeError; end 15 16 # Boilerplate for self pointer, initializer, and finalizer 17 class << self 18 alias :__new :new 19 end 20 # Attaches the pointer _ptr_ to this instance and defines a finalizer for 21 # it if necessary. 22 # @param ptr [::FFI::Pointer] 23 # @param finalize [Boolean] 24 def initialize(ptr, finalize = true) 25 @ptr = ptr 26 if @ptr.null? 27 @ptr = nil # Remove null pointers so we don't have to test for them. 28 elsif finalize 29 @finalizer = self.class.create_finalizer_for @ptr 30 ObjectSpace.define_finalizer self, @finalizer 31 end 32 end 33 # @param ptr [::FFI::Pointer] 34 # @return [Proc] 35 def self.create_finalizer_for(ptr) 36 Proc.new do 37 ptr_ptr = ::FFI::MemoryPointer.new :pointer 38 ptr_ptr.write_pointer ptr 39 ::CZMQ::FFI.zmsg_destroy ptr_ptr 40 end 41 end 42 # @return [Boolean] 43 def null? 44 !@ptr or @ptr.null? 45 end 46 # Return internal pointer 47 # @return [::FFI::Pointer] 48 def __ptr 49 raise DestroyedError unless @ptr 50 @ptr 51 end 52 # So external Libraries can just pass the Object to a FFI function which expects a :pointer 53 alias_method :to_ptr, :__ptr 54 # Nullify internal pointer and return pointer pointer. 55 # @note This detaches the current instance from the native object 56 # and thus makes it unusable. 57 # @return [::FFI::MemoryPointer] the pointer pointing to a pointer 58 # pointing to the native object 59 def __ptr_give_ref 60 raise DestroyedError unless @ptr 61 ptr_ptr = ::FFI::MemoryPointer.new :pointer 62 ptr_ptr.write_pointer @ptr 63 __undef_finalizer if @finalizer 64 @ptr = nil 65 ptr_ptr 66 end 67 # Undefines the finalizer for this object. 68 # @note Only use this if you need to and can guarantee that the native 69 # object will be freed by other means. 70 # @return [void] 71 def __undef_finalizer 72 ObjectSpace.undefine_finalizer self 73 @finalizer = nil 74 end 75 76 # Create a new empty message object 77 # @return [CZMQ::Zmsg] 78 def self.new() 79 ptr = ::CZMQ::FFI.zmsg_new() 80 __new ptr 81 end 82 83 # Receive message from socket, returns zmsg_t object or NULL if the recv 84 # was interrupted. Does a blocking recv. If you want to not block then use 85 # the zloop class or zmsg_recv_nowait or zmq_poll to check for socket input 86 # before receiving. 87 # @param source [::FFI::Pointer, #to_ptr] 88 # @return [CZMQ::Zmsg] 89 def self.recv(source) 90 ptr = ::CZMQ::FFI.zmsg_recv(source) 91 __new ptr 92 end 93 94 # Load/append an open file into new message, return the message. 95 # Returns NULL if the message could not be loaded. 96 # @param file [::FFI::Pointer, #to_ptr] 97 # @return [CZMQ::Zmsg] 98 def self.load(file) 99 ptr = ::CZMQ::FFI.zmsg_load(file) 100 __new ptr 101 end 102 103 # Decodes a serialized message frame created by zmsg_encode () and returns 104 # a new zmsg_t object. Returns NULL if the frame was badly formatted or 105 # there was insufficient memory to work. 106 # @param frame [Zframe, #__ptr] 107 # @return [CZMQ::Zmsg] 108 def self.decode(frame) 109 frame = frame.__ptr if frame 110 ptr = ::CZMQ::FFI.zmsg_decode(frame) 111 __new ptr 112 end 113 114 # Generate a signal message encoding the given status. A signal is a short 115 # message carrying a 1-byte success/failure code (by convention, 0 means 116 # OK). Signals are encoded to be distinguishable from "normal" messages. 117 # @param status [Integer, #to_int, #to_i] 118 # @return [CZMQ::Zmsg] 119 def self.new_signal(status) 120 status = Integer(status) 121 ptr = ::CZMQ::FFI.zmsg_new_signal(status) 122 __new ptr 123 end 124 125 # Destroy a message object and all frames it contains 126 # 127 # @return [void] 128 def destroy() 129 return unless @ptr 130 self_p = __ptr_give_ref 131 result = ::CZMQ::FFI.zmsg_destroy(self_p) 132 result 133 end 134 135 # Send message to destination socket, and destroy the message after sending 136 # it successfully. If the message has no frames, sends nothing but destroys 137 # the message anyhow. Nullifies the caller's reference to the message (as 138 # it is a destructor). 139 # 140 # @param self_p [#__ptr_give_ref] 141 # @param dest [::FFI::Pointer, #to_ptr] 142 # @return [Integer] 143 def self.send(self_p, dest) 144 self_p = self_p.__ptr_give_ref 145 result = ::CZMQ::FFI.zmsg_send(self_p, dest) 146 result 147 end 148 149 # Send message to destination socket as part of a multipart sequence, and 150 # destroy the message after sending it successfully. Note that after a 151 # zmsg_sendm, you must call zmsg_send or another method that sends a final 152 # message part. If the message has no frames, sends nothing but destroys 153 # the message anyhow. Nullifies the caller's reference to the message (as 154 # it is a destructor). 155 # 156 # @param self_p [#__ptr_give_ref] 157 # @param dest [::FFI::Pointer, #to_ptr] 158 # @return [Integer] 159 def self.sendm(self_p, dest) 160 self_p = self_p.__ptr_give_ref 161 result = ::CZMQ::FFI.zmsg_sendm(self_p, dest) 162 result 163 end 164 165 # Return size of message, i.e. number of frames (0 or more). 166 # 167 # @return [Integer] 168 def size() 169 raise DestroyedError unless @ptr 170 self_p = @ptr 171 result = ::CZMQ::FFI.zmsg_size(self_p) 172 result 173 end 174 175 # Return total size of all frames in message. 176 # 177 # @return [Integer] 178 def content_size() 179 raise DestroyedError unless @ptr 180 self_p = @ptr 181 result = ::CZMQ::FFI.zmsg_content_size(self_p) 182 result 183 end 184 185 # Return message routing ID, if the message came from a ZMQ_SERVER socket. 186 # Else returns zero. 187 # 188 # @return [Integer] 189 def routing_id() 190 raise DestroyedError unless @ptr 191 self_p = @ptr 192 result = ::CZMQ::FFI.zmsg_routing_id(self_p) 193 result 194 end 195 196 # Set routing ID on message. This is used if/when the message is sent to a 197 # ZMQ_SERVER socket. 198 # 199 # @param routing_id [Integer, #to_int, #to_i] 200 # @return [void] 201 def set_routing_id(routing_id) 202 raise DestroyedError unless @ptr 203 self_p = @ptr 204 routing_id = Integer(routing_id) 205 result = ::CZMQ::FFI.zmsg_set_routing_id(self_p, routing_id) 206 result 207 end 208 209 # Push frame to the front of the message, i.e. before all other frames. 210 # Message takes ownership of frame, will destroy it when message is sent. 211 # Returns 0 on success, -1 on error. Deprecates zmsg_push, which did not 212 # nullify the caller's frame reference. 213 # 214 # @param frame_p [#__ptr_give_ref] 215 # @return [Integer] 216 def prepend(frame_p) 217 raise DestroyedError unless @ptr 218 self_p = @ptr 219 frame_p = frame_p.__ptr_give_ref 220 result = ::CZMQ::FFI.zmsg_prepend(self_p, frame_p) 221 result 222 end 223 224 # Add frame to the end of the message, i.e. after all other frames. 225 # Message takes ownership of frame, will destroy it when message is sent. 226 # Returns 0 on success. Deprecates zmsg_add, which did not nullify the 227 # caller's frame reference. 228 # 229 # @param frame_p [#__ptr_give_ref] 230 # @return [Integer] 231 def append(frame_p) 232 raise DestroyedError unless @ptr 233 self_p = @ptr 234 frame_p = frame_p.__ptr_give_ref 235 result = ::CZMQ::FFI.zmsg_append(self_p, frame_p) 236 result 237 end 238 239 # Remove first frame from message, if any. Returns frame, or NULL. 240 # 241 # @return [Zframe] 242 def pop() 243 raise DestroyedError unless @ptr 244 self_p = @ptr 245 result = ::CZMQ::FFI.zmsg_pop(self_p) 246 result = Zframe.__new result, true 247 result 248 end 249 250 # Push block of memory to front of message, as a new frame. 251 # Returns 0 on success, -1 on error. 252 # 253 # @param data [::FFI::Pointer, #to_ptr] 254 # @param size [Integer, #to_int, #to_i] 255 # @return [Integer] 256 def pushmem(data, size) 257 raise DestroyedError unless @ptr 258 self_p = @ptr 259 size = Integer(size) 260 result = ::CZMQ::FFI.zmsg_pushmem(self_p, data, size) 261 result 262 end 263 264 # Add block of memory to the end of the message, as a new frame. 265 # Returns 0 on success, -1 on error. 266 # 267 # @param data [::FFI::Pointer, #to_ptr] 268 # @param size [Integer, #to_int, #to_i] 269 # @return [Integer] 270 def addmem(data, size) 271 raise DestroyedError unless @ptr 272 self_p = @ptr 273 size = Integer(size) 274 result = ::CZMQ::FFI.zmsg_addmem(self_p, data, size) 275 result 276 end 277 278 # Push string as new frame to front of message. 279 # Returns 0 on success, -1 on error. 280 # 281 # @param string [String, #to_s, nil] 282 # @return [Integer] 283 def pushstr(string) 284 raise DestroyedError unless @ptr 285 self_p = @ptr 286 result = ::CZMQ::FFI.zmsg_pushstr(self_p, string) 287 result 288 end 289 290 # Push string as new frame to end of message. 291 # Returns 0 on success, -1 on error. 292 # 293 # @param string [String, #to_s, nil] 294 # @return [Integer] 295 def addstr(string) 296 raise DestroyedError unless @ptr 297 self_p = @ptr 298 result = ::CZMQ::FFI.zmsg_addstr(self_p, string) 299 result 300 end 301 302 # Push formatted string as new frame to front of message. 303 # Returns 0 on success, -1 on error. 304 # 305 # @param format [String, #to_s, nil] 306 # @param args [Array<Object>] see https://github.com/ffi/ffi/wiki/examples#using-varargs 307 # @return [Integer] 308 def pushstrf(format, *args) 309 raise DestroyedError unless @ptr 310 self_p = @ptr 311 result = ::CZMQ::FFI.zmsg_pushstrf(self_p, format, *args) 312 result 313 end 314 315 # Push formatted string as new frame to end of message. 316 # Returns 0 on success, -1 on error. 317 # 318 # @param format [String, #to_s, nil] 319 # @param args [Array<Object>] see https://github.com/ffi/ffi/wiki/examples#using-varargs 320 # @return [Integer] 321 def addstrf(format, *args) 322 raise DestroyedError unless @ptr 323 self_p = @ptr 324 result = ::CZMQ::FFI.zmsg_addstrf(self_p, format, *args) 325 result 326 end 327 328 # Pop frame off front of message, return as fresh string. If there were 329 # no more frames in the message, returns NULL. 330 # 331 # @return [::FFI::AutoPointer] 332 def popstr() 333 raise DestroyedError unless @ptr 334 self_p = @ptr 335 result = ::CZMQ::FFI.zmsg_popstr(self_p) 336 result = ::FFI::AutoPointer.new(result, LibC.method(:free)) 337 result 338 end 339 340 # Push encoded message as a new frame. Message takes ownership of 341 # submessage, so the original is destroyed in this call. Returns 0 on 342 # success, -1 on error. 343 # 344 # @param msg_p [#__ptr_give_ref] 345 # @return [Integer] 346 def addmsg(msg_p) 347 raise DestroyedError unless @ptr 348 self_p = @ptr 349 msg_p = msg_p.__ptr_give_ref 350 result = ::CZMQ::FFI.zmsg_addmsg(self_p, msg_p) 351 result 352 end 353 354 # Remove first submessage from message, if any. Returns zmsg_t, or NULL if 355 # decoding was not successful. 356 # 357 # @return [Zmsg] 358 def popmsg() 359 raise DestroyedError unless @ptr 360 self_p = @ptr 361 result = ::CZMQ::FFI.zmsg_popmsg(self_p) 362 result = Zmsg.__new result, true 363 result 364 end 365 366 # Remove specified frame from list, if present. Does not destroy frame. 367 # 368 # @param frame [Zframe, #__ptr] 369 # @return [void] 370 def remove(frame) 371 raise DestroyedError unless @ptr 372 self_p = @ptr 373 frame = frame.__ptr if frame 374 result = ::CZMQ::FFI.zmsg_remove(self_p, frame) 375 result 376 end 377 378 # Set cursor to first frame in message. Returns frame, or NULL, if the 379 # message is empty. Use this to navigate the frames as a list. 380 # 381 # @return [Zframe] 382 def first() 383 raise DestroyedError unless @ptr 384 self_p = @ptr 385 result = ::CZMQ::FFI.zmsg_first(self_p) 386 result = Zframe.__new result, false 387 result 388 end 389 390 # Return the next frame. If there are no more frames, returns NULL. To move 391 # to the first frame call zmsg_first(). Advances the cursor. 392 # 393 # @return [Zframe] 394 def next() 395 raise DestroyedError unless @ptr 396 self_p = @ptr 397 result = ::CZMQ::FFI.zmsg_next(self_p) 398 result = Zframe.__new result, false 399 result 400 end 401 402 # Return the last frame. If there are no frames, returns NULL. 403 # 404 # @return [Zframe] 405 def last() 406 raise DestroyedError unless @ptr 407 self_p = @ptr 408 result = ::CZMQ::FFI.zmsg_last(self_p) 409 result = Zframe.__new result, false 410 result 411 end 412 413 # Save message to an open file, return 0 if OK, else -1. The message is 414 # saved as a series of frames, each with length and data. Note that the 415 # file is NOT guaranteed to be portable between operating systems, not 416 # versions of CZMQ. The file format is at present undocumented and liable 417 # to arbitrary change. 418 # 419 # @param file [::FFI::Pointer, #to_ptr] 420 # @return [Integer] 421 def save(file) 422 raise DestroyedError unless @ptr 423 self_p = @ptr 424 result = ::CZMQ::FFI.zmsg_save(self_p, file) 425 result 426 end 427 428 # Serialize multipart message to a single message frame. Use this method 429 # to send structured messages across transports that do not support 430 # multipart data. Allocates and returns a new frame containing the 431 # serialized message. To decode a serialized message frame, use 432 # zmsg_decode (). 433 # 434 # @return [Zframe] 435 def encode() 436 raise DestroyedError unless @ptr 437 self_p = @ptr 438 result = ::CZMQ::FFI.zmsg_encode(self_p) 439 result = Zframe.__new result, true 440 result 441 end 442 443 # Create copy of message, as new message object. Returns a fresh zmsg_t 444 # object. If message is null, or memory was exhausted, returns null. 445 # 446 # @return [Zmsg] 447 def dup() 448 raise DestroyedError unless @ptr 449 self_p = @ptr 450 result = ::CZMQ::FFI.zmsg_dup(self_p) 451 result = Zmsg.__new result, true 452 result 453 end 454 455 # Send message to zsys log sink (may be stdout, or system facility as 456 # configured by zsys_set_logstream). 457 # 458 # @return [void] 459 def print() 460 raise DestroyedError unless @ptr 461 self_p = @ptr 462 result = ::CZMQ::FFI.zmsg_print(self_p) 463 result 464 end 465 466 # Return true if the two messages have the same number of frames and each 467 # frame in the first message is identical to the corresponding frame in the 468 # other message. As with zframe_eq, return false if either message is NULL. 469 # 470 # @param other [Zmsg, #__ptr] 471 # @return [Boolean] 472 def eq(other) 473 raise DestroyedError unless @ptr 474 self_p = @ptr 475 other = other.__ptr if other 476 result = ::CZMQ::FFI.zmsg_eq(self_p, other) 477 result 478 end 479 480 # Return signal value, 0 or greater, if message is a signal, -1 if not. 481 # 482 # @return [Integer] 483 def signal() 484 raise DestroyedError unless @ptr 485 self_p = @ptr 486 result = ::CZMQ::FFI.zmsg_signal(self_p) 487 result 488 end 489 490 # Probe the supplied object, and report if it looks like a zmsg_t. 491 # 492 # @param self_ [::FFI::Pointer, #to_ptr] 493 # @return [Boolean] 494 def self.is(self_) 495 result = ::CZMQ::FFI.zmsg_is(self_) 496 result 497 end 498 499 # Self test of this class. 500 # 501 # @param verbose [Boolean] 502 # @return [void] 503 def self.test(verbose) 504 verbose = !(0==verbose||!verbose) # boolean 505 result = ::CZMQ::FFI.zmsg_test(verbose) 506 result 507 end 508 end 509 end 510end 511 512################################################################################ 513# THIS FILE IS 100% GENERATED BY ZPROJECT; DO NOT EDIT EXCEPT EXPERIMENTALLY # 514# Read the zproject/README.md for information about making permanent changes. # 515################################################################################ 516