ZOSC(3)

NAME
zosc - Class for work with Open Sound Control messages

SYNOPSIS

//  This is a draft class, and may change without notice. It is disabled in
//  stable builds by default. If you use this in applications, please ask
//  for it to be pushed to stable state. Use --enable-drafts to enable.
#ifdef CZMQ_BUILD_DRAFT_API
//  *** Draft method, for development use, may change without warning ***
//  Create a new empty OSC message with the specified address string.
CZMQ_EXPORT zosc_t *
    zosc_new (const char *address);
//  *** Draft method, for development use, may change without warning ***
//  Create a new OSC message from the specified zframe. Takes ownership of
//  the zframe.
CZMQ_EXPORT zosc_t *
    zosc_fromframe (zframe_t *frame);
//  *** Draft method, for development use, may change without warning ***
//  Create a new zosc message from memory. Take ownership of the memory
//  and calling free on the data after construction.
CZMQ_EXPORT zosc_t *
    zosc_frommem (char *data, size_t size);
//  *** Draft method, for development use, may change without warning ***
//  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
CZMQ_EXPORT zosc_t *
    zosc_create (const char *address, const char *format, ...);
//  *** Draft method, for development use, may change without warning ***
//  Destroy an OSC message
CZMQ_EXPORT void
    zosc_destroy (zosc_t **self_p);
//  *** Draft method, for development use, may change without warning ***
//  Return chunk data size
CZMQ_EXPORT size_t
    zosc_size (zosc_t *self);
//  *** Draft method, for development use, may change without warning ***
//  Return OSC chunk data. Caller does not own the data!
CZMQ_EXPORT byte *
    zosc_data (zosc_t *self);
//  *** Draft method, for development use, may change without warning ***
//  Return the OSC address string
CZMQ_EXPORT const char *
    zosc_address (zosc_t *self);
//  *** Draft method, for development use, may change without warning ***
//  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
CZMQ_EXPORT const char *
    zosc_format (zosc_t *self);
//  *** Draft method, for development use, may change without warning ***
//  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
CZMQ_EXPORT int
    zosc_append (zosc_t *self, const char *format, ...);
//  *** Draft method, for development use, may change without warning ***
//  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.
CZMQ_EXPORT int
    zosc_retr (zosc_t *self, const char *format, ...);
//  *** Draft method, for development use, may change without warning ***
//  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.
//  Caller owns return value and must destroy it when done.
CZMQ_EXPORT zosc_t *
    zosc_dup (zosc_t *self);
//  *** Draft method, for development use, may change without warning ***
//  Transform zosc into a zframe that can be sent in a message.
//  Caller owns return value and must destroy it when done.
CZMQ_EXPORT zframe_t *
    zosc_pack (zosc_t *self);
//  *** Draft method, for development use, may change without warning ***
//  Transform zosc into a zframe that can be sent in a message.
//  Take ownership of the chunk.
//  Caller owns return value and must destroy it when done.
CZMQ_EXPORT zframe_t *
    zosc_packx (zosc_t **self_p);
//  *** Draft method, for development use, may change without warning ***
//  Transform a zframe into a zosc.
//  Caller owns return value and must destroy it when done.
CZMQ_EXPORT zosc_t *
    zosc_unpack (zframe_t *frame);
//  *** Draft method, for development use, may change without warning ***
//  Dump OSC message to stdout, for debugging and tracing.
CZMQ_EXPORT void
    zosc_print (zosc_t *self);
//  *** Draft method, for development use, may change without warning ***
//  Probe the supplied object, and report if it looks like a zosc_t.
CZMQ_EXPORT bool
    zosc_is (void *self);
//  *** Draft method, for development use, may change without warning ***
//  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.
CZMQ_EXPORT const void *
    zosc_first (zosc_t *self, char *type);
//  *** Draft method, for development use, may change without warning ***
//  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 ().
CZMQ_EXPORT const void *
    zosc_next (zosc_t *self, char *type);
//  *** Draft method, for development use, may change without warning ***
//  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.
CZMQ_EXPORT const void *
    zosc_last (zosc_t *self, char *type);
//  *** Draft method, for development use, may change without warning ***
//  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.
CZMQ_EXPORT int
    zosc_pop_int32 (zosc_t *self, int *val);
//  *** Draft method, for development use, may change without warning ***
//  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.
CZMQ_EXPORT int
    zosc_pop_int64 (zosc_t *self, int64_t *val);
//  *** Draft method, for development use, may change without warning ***
//  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.
CZMQ_EXPORT int
    zosc_pop_float (zosc_t *self, float *val);
//  *** Draft method, for development use, may change without warning ***
//  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.
CZMQ_EXPORT int
    zosc_pop_double (zosc_t *self, double *val);
//  *** Draft method, for development use, may change without warning ***
//  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!
CZMQ_EXPORT int
    zosc_pop_string (zosc_t *self, char **val);
//  *** Draft method, for development use, may change without warning ***
//  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.
CZMQ_EXPORT int
    zosc_pop_char (zosc_t *self, char *val);
//  *** Draft method, for development use, may change without warning ***
//  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.
CZMQ_EXPORT int
    zosc_pop_bool (zosc_t *self, bool *val);
//  *** Draft method, for development use, may change without warning ***
//  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.
CZMQ_EXPORT int
    zosc_pop_midi (zosc_t *self, uint32_t *val);
//  *** Draft method, for development use, may change without warning ***
//  Self test of this class.
CZMQ_EXPORT void
    zosc_test (bool verbose);
#endif // CZMQ_BUILD_DRAFT_API
Please add '@interface' section in '/home/builder/.termux-build/libczmq/src/doc/../src/zosc.c'.

DESCRIPTION

zosc - work with Open Sound Control messages

Please add @discuss section in /home/builder/.termux-build/libczmq/src/doc/../src/zosc.c.

EXAMPLE

From zosc_test method.

    // we need to have packets on the heap
    char *p1 = (char *)malloc(40);
    memcpy(p1, oscpacket, 40);
    zosc_t *self = zosc_frommem(p1, 40);
    assert (self);
    assert ( zosc_is( self ));
    assert(streq ( zosc_address(self), "/sample/address"));
    assert(streq ( zosc_format(self), "iTfs"));
    // check value
    uint32_t test = 0;
    bool b = false;
    float f = 0.f;
    char *s = "BLA";
    zosc_retr(self, "iTfs", &test, &b, &f, &s);
    assert(test == 1);
    assert(b);
    assert(fabsf(f - 3.14f) < FLT_EPSILON); // float equal
    assert(streq(s, "hello"));
    zstr_free(&s);
    zosc_destroy (&self);
    zframe_t *frame = zframe_new(oscpacket, 40);
    assert(frame);
    assert(zframe_size(frame) == 40);
    zosc_t *fosc = zosc_fromframe(frame);
    assert (fosc);
    assert(streq ( zosc_address(fosc), "/sample/address"));
    assert(streq ( zosc_format(fosc), "iTfs"));
    // test skipping retrieving values
    zosc_retr(fosc, "iTfs", NULL, NULL, NULL, NULL);
    char *fstr = "";
    zosc_retr(fosc, "iTfs", NULL, NULL, NULL, &fstr);
    assert( streq(fstr, "hello") );
    zstr_free(&fstr);
    zosc_destroy (&fosc);
    // to the heap, otherwise we can't destroy
    char *p2 = (char *)malloc(48);
    memcpy(p2, testpack, 48);
    zosc_t *testmsg = zosc_frommem(p2, 48);
    assert( testmsg );
    assert(streq ( zosc_address(testmsg), "/test"));
    assert(streq ( zosc_format(testmsg), "ihTfds" ) );
    // test duplicate
    zosc_t *testmsgdup = zosc_dup(NULL);
    assert( testmsgdup == NULL );
    testmsgdup = zosc_dup(testmsg);
    assert( testmsgdup );
    assert(streq ( zosc_address(testmsgdup), "/test"));
    assert(streq ( zosc_format(testmsgdup), "ihTfds" ) );
    zosc_destroy(&testmsgdup);
    // check value
    int itest = -1;
    int64_t ltest = -1;
    bool btest = false;
    float ftest = -1.f;
    double dtest = -1.;
    char *stest;
    const char *format = zosc_format(testmsg);
    zosc_retr(testmsg, format, &itest, &ltest, &btest, &ftest, &dtest, &stest);
    assert( itest == 2 );
    assert( ltest == 1844674407370 );
    assert( btest );
    assert( fabsf(ftest - 3.14f) < FLT_EPSILON ); // float equal
    assert( fabs(dtest - 3.1415926535897932) < DBL_EPSILON );
    assert( streq(stest, "hello") );
    zstr_free(&stest);
    zosc_destroy(&testmsg);
    // test constructing messages
    int64_t prez = 3;
    zosc_t* conm = zosc_create("/construct", "iihfdscF", -2,2, prez, 3.14,6.283185307179586, "greetings", 'q');
    assert(conm);
    assert(streq(zosc_address(conm), "/construct"));
    assert(streq(zosc_format(conm), "iihfdscF"));
    if (verbose) zosc_print(conm);
    int x,y;
    int64_t z;
    float zz;
    double zzz;
    char *ss = "aliens";
    char q = 'z';
    bool Ftest = true;
    zosc_retr(conm, "iihfdscF", &x, &y, &z, &zz, &zzz, &ss, &q, &Ftest);
    assert( x==-2 );
    assert( y==2 );
    assert( z==3 );
    assert( fabsf(zz-3.14f) < FLT_EPSILON );
    assert( fabs(zzz-6.283185307179586) < DBL_EPSILON );
    assert( streq( ss, "greetings") );
    assert( q == 'q');
    assert( !Ftest );
    zstr_free(&ss);
    // test iterating
    char type = '0';
    const void *data = zosc_first(conm, &type);
    while ( data )
    {
        if (verbose)
            zsys_info("type tag is %c", type);
        switch (type)
        {
        case('i'):
        {
            int32_t test = 9;
            int rc = zosc_pop_int32(conm, &test);
            assert(rc == 0);
            assert( test == -2 || test == 2);
            break;
        }
        case('h'):
        {
            int32_t fail = 9;
            int rc = zosc_pop_int32(conm, &fail); // this will fail
            assert(rc == -1);
            int64_t test = 9;
            rc = zosc_pop_int64(conm, &test);
            assert(rc == 0);
            assert( test == 3 );
            break;
        }
        case('f'):
        {
            float flt_v = 0.f;
            int rc = zosc_pop_float(conm, &flt_v);
            assert(rc == 0);
            assert( fabsf(flt_v-3.14f) < FLT_EPSILON );
            break;
        }
        case 'd':
        {
            double dbl_v = 0.;
            int rc = zosc_pop_double(conm, &dbl_v);
            assert(rc == 0);
            assert( fabs(dbl_v-6.283185307179586) < DBL_EPSILON );
            break;
        }
        case 's':
        {
            char *str;
            int rc = zosc_pop_string(conm, &str);
            assert(rc == 0);
            assert(streq(str, "greetings"));
            zstr_free(&str);
            break;
        }
        case 'c':
        {
            char chr;
            int rc = zosc_pop_char(conm, &chr);
            assert(rc == 0);
            assert(chr == 'q');
            break;
        }
        case 'F':
        {
            bool bl;
            int rc = zosc_pop_bool(conm, &bl);
            assert(rc == 0);
            assert( !bl );
            break;
        }
        default:
            assert(0);
        }
        data = zosc_next(conm, &type);
    }
    // test append
    int64_t preal = -80000;
    zosc_append(conm, "ih", -200, preal);
    int ax,ay;
    int64_t az;
    float azz;
    double azzz;
    char *ass = "aliens";
    char aq = 'z';
    bool aFtest = true;
    int ai = 0;
    int64_t al = 0;
    zosc_retr(conm, "iihfdscFih", &ax, &ay, &az, &azz, &azzz, &ass, &aq, &aFtest, &ai, &al);
    assert( ax==-2 );
    assert( ay==2 );
    assert( az==3 );
    assert( fabsf(azz-3.14f) < FLT_EPSILON );
    assert( fabs(azzz-6.283185307179586) < DBL_EPSILON );
    assert( streq( ass, "greetings") );
    assert( aq == 'q');
    assert( !aFtest );
    assert( ai==-200 );
    assert( al==-80000 );
    zstr_free(&ass);
    #ifdef ZMQ_DGRAM
    zsock_t *dgrams = zsock_new_dgram("udp://*:*");
    assert (dgrams);
    zframe_t *t = zosc_pack(conm);
    zstr_sendm( dgrams, "127.0.0.1:7777" );
    zframe_send( &t, dgrams, 0);
    zclock_sleep(10); // slow down, otherwise we've cleaned up before async send
    zsock_destroy( &dgrams );
    #else
    int sockfd;
    struct sockaddr_in     servaddr;
    // Creating socket file descriptor
    if ( (sockfd = (int)socket(AF_INET, SOCK_DGRAM, 0)) < 0 ) {
        zsys_error("socket creation failed");
    }
    memset(&servaddr, 0, sizeof(servaddr));
    // Filling server information
    servaddr.sin_family = AF_INET;
    servaddr.sin_port = htons(7777);
    servaddr.sin_addr.s_addr = INADDR_ANY;
    #ifdef __WINDOWS__
    sendto(sockfd, (const char *)zosc_data(conm), (int)zosc_size(conm),
            0, (const struct sockaddr *) &servaddr,
                sizeof(servaddr));
    #else
    sendto(sockfd, zosc_data(conm), zosc_size(conm),
            0, (const struct sockaddr *) &servaddr,
                sizeof(servaddr));
    #endif
    #endif
    zosc_destroy(&conm);
    #ifdef __WINDOWS__
    zsys_shutdown();
    #endif

AUTHORS

The czmq manual was written by the authors in the AUTHORS file.

RESOURCES

Main web site:

Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>

COPYRIGHT

Copyright (c) the Contributors as noted in the AUTHORS file. This file is part of CZMQ, the high-level C binding for 0MQ: http://czmq.zeromq.org. This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. LICENSE included with the czmq distribution.

NOTES

1.  zeromq-dev@lists.zeromq.org
    mailto:zeromq-dev@lists.zeromq.org