mlm_proto(3)
============

NAME
----
mlm_proto - The Malamute Protocol

SYNOPSIS
--------
----
//  Create a new empty mlm_proto
MLM_EXPORT mlm_proto_t *
    mlm_proto_new (void);

//  Destroy a mlm_proto instance
MLM_EXPORT void
    mlm_proto_destroy (mlm_proto_t **self_p);

//  Receive a mlm_proto from the socket. Returns 0 if OK, -1 if
//  there was an error. Blocks if there is no message waiting.
MLM_EXPORT int
    mlm_proto_recv (mlm_proto_t *self, zsock_t *input);

//  Send the mlm_proto to the output socket, does not destroy it
MLM_EXPORT int
    mlm_proto_send (mlm_proto_t *self, zsock_t *output);
    
//  Print contents of message to stdout
MLM_EXPORT void
    mlm_proto_print (mlm_proto_t *self);

//  Get/set the message routing id
MLM_EXPORT zframe_t *
    mlm_proto_routing_id (mlm_proto_t *self);
MLM_EXPORT void
    mlm_proto_set_routing_id (mlm_proto_t *self, zframe_t *routing_id);

//  Get the mlm_proto id and printable command
MLM_EXPORT int
    mlm_proto_id (mlm_proto_t *self);
MLM_EXPORT void
    mlm_proto_set_id (mlm_proto_t *self, int id);
MLM_EXPORT const char *
    mlm_proto_command (mlm_proto_t *self);

//  Get/set the address field
MLM_EXPORT const char *
    mlm_proto_address (mlm_proto_t *self);
MLM_EXPORT void
    mlm_proto_set_address (mlm_proto_t *self, const char *value);

//  Get/set the stream field
MLM_EXPORT const char *
    mlm_proto_stream (mlm_proto_t *self);
MLM_EXPORT void
    mlm_proto_set_stream (mlm_proto_t *self, const char *value);

//  Get/set the pattern field
MLM_EXPORT const char *
    mlm_proto_pattern (mlm_proto_t *self);
MLM_EXPORT void
    mlm_proto_set_pattern (mlm_proto_t *self, const char *value);

//  Get/set the subject field
MLM_EXPORT const char *
    mlm_proto_subject (mlm_proto_t *self);
MLM_EXPORT void
    mlm_proto_set_subject (mlm_proto_t *self, const char *value);

//  Get a copy of the content field
MLM_EXPORT zmsg_t *
    mlm_proto_content (mlm_proto_t *self);
//  Get the content field and transfer ownership to caller
MLM_EXPORT zmsg_t *
    mlm_proto_get_content (mlm_proto_t *self);
//  Set the content field, transferring ownership from caller
MLM_EXPORT void
    mlm_proto_set_content (mlm_proto_t *self, zmsg_t **msg_p);

//  Get/set the sender field
MLM_EXPORT const char *
    mlm_proto_sender (mlm_proto_t *self);
MLM_EXPORT void
    mlm_proto_set_sender (mlm_proto_t *self, const char *value);

//  Get/set the tracker field
MLM_EXPORT const char *
    mlm_proto_tracker (mlm_proto_t *self);
MLM_EXPORT void
    mlm_proto_set_tracker (mlm_proto_t *self, const char *value);

//  Get/set the timeout field
MLM_EXPORT uint32_t
    mlm_proto_timeout (mlm_proto_t *self);
MLM_EXPORT void
    mlm_proto_set_timeout (mlm_proto_t *self, uint32_t timeout);

//  Get/set the status_code field
MLM_EXPORT uint16_t
    mlm_proto_status_code (mlm_proto_t *self);
MLM_EXPORT void
    mlm_proto_set_status_code (mlm_proto_t *self, uint16_t status_code);

//  Get/set the status_reason field
MLM_EXPORT const char *
    mlm_proto_status_reason (mlm_proto_t *self);
MLM_EXPORT void
    mlm_proto_set_status_reason (mlm_proto_t *self, const char *value);

//  Get/set the amount field
MLM_EXPORT uint16_t
    mlm_proto_amount (mlm_proto_t *self);
MLM_EXPORT void
    mlm_proto_set_amount (mlm_proto_t *self, uint16_t amount);

//  Self test of this class
MLM_EXPORT int
    mlm_proto_test (bool verbose);
----

DESCRIPTION
-----------

mlm_proto - The Malamute Protocol

Please add @discuss section in ../src/mlm_proto.c.

EXAMPLE
-------
.From mlm_proto_test method
----
//  Simple create/destroy test
mlm_proto_t *self = mlm_proto_new ();
assert (self);
mlm_proto_destroy (&self);

//  Create pair of sockets we can send through
zsock_t *input = zsock_new (ZMQ_ROUTER);
assert (input);
zsock_connect (input, "inproc://selftest-mlm_proto");

zsock_t *output = zsock_new (ZMQ_DEALER);
assert (output);
zsock_bind (output, "inproc://selftest-mlm_proto");

//  Encode/send/decode and verify each message type
int instance;
self = mlm_proto_new ();
mlm_proto_set_id (self, mlm_proto_CONNECTION_OPEN);

mlm_proto_set_address (self, "Life is short but Now lasts for ever");
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (streq (mlm_proto_address (self), "Life is short but Now lasts for ever"));
}
mlm_proto_set_id (self, mlm_proto_CONNECTION_PING);

//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
}
mlm_proto_set_id (self, mlm_proto_CONNECTION_PONG);

//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
}
mlm_proto_set_id (self, mlm_proto_CONNECTION_CLOSE);

//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
}
mlm_proto_set_id (self, mlm_proto_STREAM_WRITE);

mlm_proto_set_stream (self, "Life is short but Now lasts for ever");
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (streq (mlm_proto_stream (self), "Life is short but Now lasts for ever"));
}
mlm_proto_set_id (self, mlm_proto_STREAM_READ);

mlm_proto_set_stream (self, "Life is short but Now lasts for ever");
mlm_proto_set_pattern (self, "Life is short but Now lasts for ever");
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (streq (mlm_proto_stream (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_pattern (self), "Life is short but Now lasts for ever"));
}
mlm_proto_set_id (self, mlm_proto_STREAM_SEND);

mlm_proto_set_subject (self, "Life is short but Now lasts for ever");
zmsg_t *stream_send_content = zmsg_new ();
mlm_proto_set_content (self, &stream_send_content);
zmsg_addstr (mlm_proto_content (self), "Hello, World");
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (streq (mlm_proto_subject (self), "Life is short but Now lasts for ever"));
    assert (zmsg_size (mlm_proto_content (self)) == 1);
}
mlm_proto_set_id (self, mlm_proto_STREAM_DELIVER);

mlm_proto_set_stream (self, "Life is short but Now lasts for ever");
mlm_proto_set_sender (self, "Life is short but Now lasts for ever");
mlm_proto_set_subject (self, "Life is short but Now lasts for ever");
zmsg_t *stream_deliver_content = zmsg_new ();
mlm_proto_set_content (self, &stream_deliver_content);
zmsg_addstr (mlm_proto_content (self), "Hello, World");
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (streq (mlm_proto_stream (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_sender (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_subject (self), "Life is short but Now lasts for ever"));
    assert (zmsg_size (mlm_proto_content (self)) == 1);
}
mlm_proto_set_id (self, mlm_proto_MAILBOX_SEND);

mlm_proto_set_address (self, "Life is short but Now lasts for ever");
mlm_proto_set_subject (self, "Life is short but Now lasts for ever");
mlm_proto_set_tracker (self, "Life is short but Now lasts for ever");
mlm_proto_set_timeout (self, 123);
zmsg_t *mailbox_send_content = zmsg_new ();
mlm_proto_set_content (self, &mailbox_send_content);
zmsg_addstr (mlm_proto_content (self), "Hello, World");
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (streq (mlm_proto_address (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_subject (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_tracker (self), "Life is short but Now lasts for ever"));
    assert (mlm_proto_timeout (self) == 123);
    assert (zmsg_size (mlm_proto_content (self)) == 1);
}
mlm_proto_set_id (self, mlm_proto_MAILBOX_DELIVER);

mlm_proto_set_sender (self, "Life is short but Now lasts for ever");
mlm_proto_set_address (self, "Life is short but Now lasts for ever");
mlm_proto_set_subject (self, "Life is short but Now lasts for ever");
mlm_proto_set_tracker (self, "Life is short but Now lasts for ever");
zmsg_t *mailbox_deliver_content = zmsg_new ();
mlm_proto_set_content (self, &mailbox_deliver_content);
zmsg_addstr (mlm_proto_content (self), "Hello, World");
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (streq (mlm_proto_sender (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_address (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_subject (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_tracker (self), "Life is short but Now lasts for ever"));
    assert (zmsg_size (mlm_proto_content (self)) == 1);
}
mlm_proto_set_id (self, mlm_proto_SERVICE_SEND);

mlm_proto_set_address (self, "Life is short but Now lasts for ever");
mlm_proto_set_subject (self, "Life is short but Now lasts for ever");
mlm_proto_set_tracker (self, "Life is short but Now lasts for ever");
mlm_proto_set_timeout (self, 123);
zmsg_t *service_send_content = zmsg_new ();
mlm_proto_set_content (self, &service_send_content);
zmsg_addstr (mlm_proto_content (self), "Hello, World");
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (streq (mlm_proto_address (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_subject (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_tracker (self), "Life is short but Now lasts for ever"));
    assert (mlm_proto_timeout (self) == 123);
    assert (zmsg_size (mlm_proto_content (self)) == 1);
}
mlm_proto_set_id (self, mlm_proto_SERVICE_OFFER);

mlm_proto_set_address (self, "Life is short but Now lasts for ever");
mlm_proto_set_pattern (self, "Life is short but Now lasts for ever");
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (streq (mlm_proto_address (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_pattern (self), "Life is short but Now lasts for ever"));
}
mlm_proto_set_id (self, mlm_proto_SERVICE_DELIVER);

mlm_proto_set_sender (self, "Life is short but Now lasts for ever");
mlm_proto_set_address (self, "Life is short but Now lasts for ever");
mlm_proto_set_subject (self, "Life is short but Now lasts for ever");
mlm_proto_set_tracker (self, "Life is short but Now lasts for ever");
zmsg_t *service_deliver_content = zmsg_new ();
mlm_proto_set_content (self, &service_deliver_content);
zmsg_addstr (mlm_proto_content (self), "Hello, World");
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (streq (mlm_proto_sender (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_address (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_subject (self), "Life is short but Now lasts for ever"));
    assert (streq (mlm_proto_tracker (self), "Life is short but Now lasts for ever"));
    assert (zmsg_size (mlm_proto_content (self)) == 1);
}
mlm_proto_set_id (self, mlm_proto_OK);

mlm_proto_set_status_code (self, 123);
mlm_proto_set_status_reason (self, "Life is short but Now lasts for ever");
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (mlm_proto_status_code (self) == 123);
    assert (streq (mlm_proto_status_reason (self), "Life is short but Now lasts for ever"));
}
mlm_proto_set_id (self, mlm_proto_ERROR);

mlm_proto_set_status_code (self, 123);
mlm_proto_set_status_reason (self, "Life is short but Now lasts for ever");
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (mlm_proto_status_code (self) == 123);
    assert (streq (mlm_proto_status_reason (self), "Life is short but Now lasts for ever"));
}
mlm_proto_set_id (self, mlm_proto_CREDIT);

mlm_proto_set_amount (self, 123);
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (mlm_proto_amount (self) == 123);
}
mlm_proto_set_id (self, mlm_proto_CONFIRM);

mlm_proto_set_tracker (self, "Life is short but Now lasts for ever");
mlm_proto_set_status_code (self, 123);
mlm_proto_set_status_reason (self, "Life is short but Now lasts for ever");
//  Send twice
mlm_proto_send (self, output);
mlm_proto_send (self, output);

for (instance = 0; instance < 2; instance++) {
    mlm_proto_recv (self, input);
    assert (mlm_proto_routing_id (self));
    assert (streq (mlm_proto_tracker (self), "Life is short but Now lasts for ever"));
    assert (mlm_proto_status_code (self) == 123);
    assert (streq (mlm_proto_status_reason (self), "Life is short but Now lasts for ever"));
}

mlm_proto_destroy (&self);
zsock_destroy (&input);
zsock_destroy (&output);
----