class CZMQ::FFI::Zosc

Create and decode Open Sound Control messages. (OSC)

OSC is a serialisation format (and usually transported over UDP) which is supported by many applications and appliances. It is a de facto protocol for networking sound synthesizers, computers, and other multimedia devices for purposes such as musical performance or show control. It is also often used for rapid prototyping purposes due to the support by many applications and frameworks in this field. With ZeroMQ's DGRAM sockets it is possible to use ZeroMQ to send and receive OSC messages which can be understood by any device supporting OSC.

Example creating an OSC message:

zosc_t* conm = zosc_create("/someaddress", "iihfdscF",
                    1, 2, 3, 3.14, 6.283185307179586, "greetings", 'q');

Decoding a message:

int rc = zosc_retr(oscmsg, "iihfdscF", &intx, &inty, &intz, &floatz,
                    &doublez, &strings, &charq, &someBool);

See the class's test method for more examples how to use the class. @note This class is 100% generated using zproject.

Public Class Methods

__new(address)
Alias for: new
create(address, format, *args) click to toggle source

Create a new zosc message from the given format and arguments. The format type tags are as follows:

i - 32bit integer
h - 64bit integer
f - 32bit floating point number (IEEE)
d - 64bit (double) floating point number
s - string (NULL terminated)
t = timetag: an OSC timetag in NTP format (uint64_t)
S - symbol
c - char
m - 4 byte midi packet (8 digits hexadecimal)
T - TRUE (no value required)
F - FALSE (no value required)
N - NIL (no value required)
I - Impulse (for triggers) or INFINITUM (no value required)
b - binary blob

@param address [String, to_s, nil] @param format [String, to_s, nil] @param args [Array<Object>] @return [CZMQ::Zosc]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 146
def self.create(address, format, *args)
  ptr = ::CZMQ::FFI.zosc_create(address, format, *args)
  __new ptr
end
create_finalizer_for(ptr) click to toggle source

@param ptr [::FFI::Pointer] @return [Proc]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 56
def self.create_finalizer_for(ptr)
  Proc.new do
    ptr_ptr = ::FFI::MemoryPointer.new :pointer
    ptr_ptr.write_pointer ptr
    ::CZMQ::FFI.zosc_destroy ptr_ptr
  end
end
fromframe(frame) click to toggle source

Create a new OSC message from the specified zframe. Takes ownership of the zframe. @param frame [Zframe, #__ptr] @return [CZMQ::Zosc]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 109
def self.fromframe(frame)
  frame = frame.__ptr if frame
  ptr = ::CZMQ::FFI.zosc_fromframe(frame)
  __new ptr
end
frommem(data, size) click to toggle source

Create a new zosc message from memory. Take ownership of the memory and calling free on the data after construction. @param data [::FFI::Pointer, to_ptr] @param size [Integer, to_int, to_i] @return [CZMQ::Zosc]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 120
def self.frommem(data, size)
  size = Integer(size)
  ptr = ::CZMQ::FFI.zosc_frommem(data, size)
  __new ptr
end
is(self_) click to toggle source

Probe the supplied object, and report if it looks like a zosc_t.

@param self_ [::FFI::Pointer, to_ptr] @return [Boolean]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 323
def self.is(self_)
  result = ::CZMQ::FFI.zosc_is(self_)
  result
end
new(ptr, finalize = true) click to toggle source

Attaches the pointer ptr to this instance and defines a finalizer for it if necessary. @param ptr [::FFI::Pointer] @param finalize [Boolean]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 45
def initialize(ptr, finalize = true)
  @ptr = ptr
  if @ptr.null?
    @ptr = nil # Remove null pointers so we don't have to test for them.
  elsif finalize
    @finalizer = self.class.create_finalizer_for @ptr
    ObjectSpace.define_finalizer self, @finalizer
  end
end
new(address) click to toggle source

Create a new empty OSC message with the specified address string. @param address [String, to_s, nil] @return [CZMQ::Zosc]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 100
def self.new(address)
  ptr = ::CZMQ::FFI.zosc_new(address)
  __new ptr
end
Also aliased as: __new
packx(self_p) click to toggle source

Transform zosc into a zframe that can be sent in a message. Take ownership of the chunk.

@param self_p [#__ptr_give_ref] @return [Zframe]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 291
def self.packx(self_p)
  self_p = self_p.__ptr_give_ref
  result = ::CZMQ::FFI.zosc_packx(self_p)
  result = Zframe.__new result, true
  result
end
test(verbose) click to toggle source

Self test of this class.

@param verbose [Boolean] @return [void]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 475
def self.test(verbose)
  verbose = !(0==verbose||!verbose) # boolean
  result = ::CZMQ::FFI.zosc_test(verbose)
  result
end
unpack(frame) click to toggle source

Transform a zframe into a zosc.

@param frame [Zframe, #__ptr] @return [Zosc]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 302
def self.unpack(frame)
  frame = frame.__ptr if frame
  result = ::CZMQ::FFI.zosc_unpack(frame)
  result = Zosc.__new result, true
  result
end

Public Instance Methods

__ptr() click to toggle source

Return internal pointer @return [::FFI::Pointer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 69
def __ptr
  raise DestroyedError unless @ptr
  @ptr
end
Also aliased as: to_ptr
__ptr_give_ref() click to toggle source

Nullify internal pointer and return pointer pointer. @note This detaches the current instance from the native object

and thus makes it unusable.

@return [::FFI::MemoryPointer] the pointer pointing to a pointer

pointing to the native object
# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 80
def __ptr_give_ref
  raise DestroyedError unless @ptr
  ptr_ptr = ::FFI::MemoryPointer.new :pointer
  ptr_ptr.write_pointer @ptr
  __undef_finalizer if @finalizer
  @ptr = nil
  ptr_ptr
end
__undef_finalizer() click to toggle source

Undefines the finalizer for this object. @note Only use this if you need to and can guarantee that the native

object will be freed by other means.

@return [void]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 92
def __undef_finalizer
  ObjectSpace.undefine_finalizer self
  @finalizer = nil
end
address() click to toggle source

Return the OSC address string

@return [String]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 184
def address()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_address(self_p)
  result
end
append(format, *args) click to toggle source

Append data to the osc message. The format describes the data that needs to be appended in the message. This essentially relocates all data! The format type tags are as follows:

i - 32bit integer
h - 64bit integer
f - 32bit floating point number (IEEE)
d - 64bit (double) floating point number
s - string (NULL terminated)
t = timetag: an OSC timetag in NTP format (uint64_t)
S - symbol
c - char
m - 4 byte midi packet (8 digits hexadecimal)
T - TRUE (no value required)
F - FALSE (no value required)
N - NIL (no value required)
I - Impulse (for triggers) or INFINITUM (no value required)
b - binary blob

@param format [String, to_s, nil] @param args [Array<Object>] see github.com/ffi/ffi/wiki/examples#using-varargs @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 237
def append(format, *args)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_append(self_p, format, *args)
  result
end
data() click to toggle source

Return OSC chunk data. Caller does not own the data!

@return [::FFI::Pointer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 174
def data()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_data(self_p)
  result
end
destroy() click to toggle source

Destroy an OSC message

@return [void]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 154
def destroy()
  return unless @ptr
  self_p = __ptr_give_ref
  result = ::CZMQ::FFI.zosc_destroy(self_p)
  result
end
dup() click to toggle source

Create copy of the message, as new chunk object. Returns a fresh zosc_t object, or null if there was not enough heap memory. If chunk is null, returns null.

@return [Zosc]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 267
def dup()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_dup(self_p)
  result = Zosc.__new result, true
  result
end
first(type) click to toggle source

Return a pointer to the item at the head of the OSC data. Sets the given char argument to the type tag of the data. If the message is empty, returns NULL and the sets the given char to NULL.

@param type [::FFI::Pointer, to_ptr] @return [::FFI::Pointer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 335
def first(type)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_first(self_p, type)
  result
end
format() click to toggle source

Return the OSC format of the message.

i - 32bit integer
h - 64bit integer
f - 32bit floating point number (IEEE)
d - 64bit (double) floating point number
s - string (NULL terminated)
t = timetag: an OSC timetag in NTP format (uint64_t)
S - symbol
c - char
m - 4 byte midi packet (8 digits hexadecimal)
T - TRUE (no value required)
F - FALSE (no value required)
N - NIL (no value required)
I - Impulse (for triggers) or INFINITUM (no value required)
b - binary blob

@return [String]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 208
def format()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_format(self_p)
  result
end
last(type) click to toggle source

Return a pointer to the item at the tail of the OSC message. Sets the given char argument to the type tag of the data. If the message is empty, returns NULL.

@param type [::FFI::Pointer, to_ptr] @return [::FFI::Pointer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 360
def last(type)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_last(self_p, type)
  result
end
next(type) click to toggle source

Return the next item of the OSC message. If the list is empty, returns NULL. To move to the start of the OSC message call zosc_first ().

@param type [::FFI::Pointer, to_ptr] @return [::FFI::Pointer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 347
def next(type)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_next(self_p, type)
  result
end
null?() click to toggle source

@return [Boolean]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 64
def null?
  !@ptr or @ptr.null?
end
pack() click to toggle source

Transform zosc into a zframe that can be sent in a message.

@return [Zframe]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 278
def pack()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_pack(self_p)
  result = Zframe.__new result, true
  result
end
pop_bool(val) click to toggle source

Set the provided boolean from the type tag in the message. Booleans are not represented in the data in the message, only in the type tag. If the type tag at the current position does not correspond it will fail and return -1. Returns 0 on success.

@param val [::FFI::Pointer, to_ptr] @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 451
def pop_bool(val)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_pop_bool(self_p, val)
  result
end
pop_char(val) click to toggle source

Set the provided char from the value at the current cursor position in the message. If the type tag at the current position does not correspond it will fail and return -1. Returns 0 on success.

@param val [::FFI::Pointer, to_ptr] @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 438
def pop_char(val)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_pop_char(self_p, val)
  result
end
pop_double(val) click to toggle source

Set the provided double from the value at the current cursor position in the message. If the type tag at the current position does not correspond it will fail and return -1. Returns 0 on success.

@param val [::FFI::Pointer, to_ptr] @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 412
def pop_double(val)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_pop_double(self_p, val)
  result
end
pop_float(val) click to toggle source

Set the provided float from the value at the current cursor position in the message. If the type tag at the current position does not correspond it will fail and return -1. Returns 0 on success.

@param val [::FFI::Pointer, to_ptr] @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 399
def pop_float(val)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_pop_float(self_p, val)
  result
end
pop_int32(val) click to toggle source

Set the provided 32 bit integer from value at the current cursor position in the message. If the type tag at the current position does not correspond it will fail and return -1. Returns 0 on success.

@param val [::FFI::Pointer, to_ptr] @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 373
def pop_int32(val)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_pop_int32(self_p, val)
  result
end
pop_int64(val) click to toggle source

Set the provided 64 bit integer from the value at the current cursor position in the message. If the type tag at the current position does not correspond it will fail and return -1. Returns 0 on success.

@param val [::FFI::Pointer, to_ptr] @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 386
def pop_int64(val)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_pop_int64(self_p, val)
  result
end
pop_midi(val) click to toggle source

Set the provided 4 bytes (unsigned 32bit int) from the value at the current cursor position in the message. If the type tag at the current position does not correspond it will fail and return -1. Returns 0 on success.

@param val [::FFI::Pointer, to_ptr] @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 464
def pop_midi(val)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_pop_midi(self_p, val)
  result
end
pop_string(val) click to toggle source

Set the provided string from the value at the current cursor position in the message. If the type tag at the current position does not correspond it will fail and return -1. Returns 0 on success. Caller owns the string!

@param val [::FFI::Pointer, to_ptr] @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 425
def pop_string(val)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_pop_string(self_p, val)
  result
end
print() click to toggle source

Dump OSC message to stdout, for debugging and tracing.

@return [void]

retr(format, *args) click to toggle source

Retrieve the values provided by the given format. Note that zosc_retr creates the objects and the caller must destroy them when finished. The supplied pointers do not need to be initialized. Returns 0 if successful, or -1 if it failed to retrieve a value in which case the pointers are not modified. If an argument pointer is NULL is skips the value. See the format method for a detailed list op type tags for the format string.

@param format [String, to_s, nil] @param args [Array<Object>] see github.com/ffi/ffi/wiki/examples#using-varargs @return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 255
def retr(format, *args)
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_retr(self_p, format, *args)
  result
end
size() click to toggle source

Return chunk data size

@return [Integer]

# File lib/czmq-ffi-gen/czmq/ffi/zosc.rb, line 164
def size()
  raise DestroyedError unless @ptr
  self_p = @ptr
  result = ::CZMQ::FFI.zosc_size(self_p)
  result
end
to_ptr()

So external Libraries can just pass the Object to a FFI function which expects a :pointer

Alias for: __ptr