mlm_client.api

<!--
    ** WARNING *************************************************************
    THIS SOURCE FILE IS 100% GENERATED. If you edit this file, you will lose
    your changes at the next build cycle. This is great for temporary printf
    statements. DO NOT MAKE ANY CHANGES YOU WISH TO KEEP. The correct places
    for commits are:

     * The XML model used for this code generation: mlm_client.xml, or
     * The code generation script that built this file: zproto_client_c
    ************************************************************************
    Copyright (c) the Contributors as noted in the AUTHORS file.
    This file is part of the Malamute Project.

    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/.
 -->
<class name = "mlm_client">
    Malamute Client

        Codec class for mlm_client.
    <constructor>
        Create a new mlm_client, return the reference if successful,
        or NULL if construction failed due to lack of available memory.
    </constructor>

    <destructor>
        Destroy the mlm_client and free all memory used by the object.
    </destructor>

    <method name = "actor">
        Return actor, when caller wants to work with multiple actors and/or
        input sockets asynchronously.
        <return type = "zactor" />
    </method>

    <method name = "msgpipe">
        Return message pipe for asynchronous message I/O. In the high-volume case,
        we send methods and get replies to the actor, in a synchronous manner, and
        we send/recv high volume message data to a second pipe, the msgpipe. In
        the low-volume case we can do everything over the actor pipe, if traffic
        is never ambiguous.
        <return type = "zsock" />
    </method>

    <method name = "connected">
        Return true if client is currently connected, else false. Note that the
        client will automatically re-connect if the server dies and restarts after
        a successful first connection.
        <return type = "boolean" />
    </method>

    <method name = "set plain auth">
        Set PLAIN authentication username and password. If you do not call this, the
        client will use NULL authentication. TODO: add "set curve auth".
        Returns >= 0 if successful, -1 if interrupted.
        <argument name = "username" type = "string"></argument>
        <argument name = "password" type = "string"></argument>
        <return type = "integer" />
    </method>

    <method name = "connect">
        Connect to server endpoint, with specified timeout in msecs (zero means wait
        forever). Constructor succeeds if connection is successful. The caller may
        specify its address.
        Returns >= 0 if successful, -1 if interrupted.
        <argument name = "endpoint" type = "string">Endpoint to connect to</argument>
        <argument name = "timeout" type = "number" size = "4">Timeout in msecs</argument>
        <argument name = "address" type = "string">Unique address of caller, if any</argument>
        <return type = "integer" />
    </method>

    <method name = "set producer">
        Prepare to publish to a specified stream. After this, all messages are sent to
        this stream exclusively.
        Returns >= 0 if successful, -1 if interrupted.
        <argument name = "stream" type = "string"></argument>
        <return type = "integer" />
    </method>

    <method name = "set consumer">
        Consume messages with matching subjects. The pattern is a regular expression
        using the CZMQ zrex syntax. The most useful elements are: ^ and $ to match the
        start and end, . to match any character, \s and \S to match whitespace and
        non-whitespace, \d and \D to match a digit and non-digit, \a and \A to match
        alphabetic and non-alphabetic, \w and \W to match alphanumeric and
        non-alphanumeric, + for one or more repetitions, * for zero or more repetitions,
        and ( ) to create groups. Returns 0 if subscription was successful, else -1.
        Returns >= 0 if successful, -1 if interrupted.
        <argument name = "stream" type = "string"></argument>
        <argument name = "pattern" type = "string"></argument>
        <return type = "integer" />
    </method>

    <method name = "remove consumer">
        Remove all subscriptions to a stream
        Returns >= 0 if successful, -1 if interrupted.
        <argument name = "stream" type = "string"></argument>
        <return type = "integer" />
    </method>

    <method name = "set worker">
        Offer a particular named service, where the pattern matches request subjects
        using the CZMQ zrex syntax.
        Returns >= 0 if successful, -1 if interrupted.
        <argument name = "address" type = "string"></argument>
        <argument name = "pattern" type = "string"></argument>
        <return type = "integer" />
    </method>

    <method name = "send">
        Send STREAM SEND message to server, takes ownership of message
        and destroys message when done sending it.
        <argument name = "subject" type = "string">Message subject</argument>
        <argument name = "content" type = "zmsg" by_reference = "1">Message body frames</argument>
        <return type = "integer" />
    </method>

    <method name = "sendto">
        Send MAILBOX SEND message to server, takes ownership of message
        and destroys message when done sending it.
        <argument name = "address" type = "string">Mailbox address</argument>
        <argument name = "subject" type = "string">Message subject</argument>
        <argument name = "tracker" type = "string">Message tracker</argument>
        <argument name = "timeout" type = "number" size = "4">Timeout, msecs, or zero</argument>
        <argument name = "content" type = "zmsg" by_reference = "1">Message body frames</argument>
        <return type = "integer" />
    </method>

    <method name = "sendfor">
        Send SERVICE SEND message to server, takes ownership of message
        and destroys message when done sending it.
        <argument name = "address" type = "string">Service address</argument>
        <argument name = "subject" type = "string">Message subject</argument>
        <argument name = "tracker" type = "string">Message tracker</argument>
        <argument name = "timeout" type = "number" size = "4">Timeout, msecs, or zero</argument>
        <argument name = "content" type = "zmsg" by_reference = "1">Message body frames</argument>
        <return type = "integer" />
    </method>

    <method name = "recv">
        Receive message from server; caller destroys message when done
        <return type = "zmsg" fresh = "1" />
    </method>

    <method name = "command">
        Return last received command. Can be one of these values:
            "STREAM DELIVER"
            "MAILBOX DELIVER"
            "SERVICE DELIVER"
        <return type = "string" />
    </method>

    <method name = "status">
        Return last received status
        <return type = "integer" />
    </method>

    <method name = "reason">
        Return last received reason
        <return type = "string" />
    </method>

    <method name = "address">
        Return last received address
        <return type = "string" />
    </method>

    <method name = "sender">
        Return last received sender
        <return type = "string" />
    </method>

    <method name = "subject">
        Return last received subject
        <return type = "string" />
    </method>

    <method name = "content">
        Return last received content
        <return type = "zmsg" />
    </method>

    <method name = "tracker">
        Return last received tracker
        <return type = "string" />
    </method>


    <!-- This is the API definition for custom code -->
    <method name = "sendx">
        Send multipart string message to stream, end list with NULL
        Returns 0 if OK, -1 if failed due to lack of memory or other error.
        <argument name = "subject" type = "string" />
        <argument name = "content" type = "string" variadic = "1" />
        <return type = "integer" />
    </method>

    <method name = "sendtox">
        Send multipart string to mailbox, end list with NULL
        Returns 0 if OK, -1 if failed due to lack of memory or other error.
        <argument name = "address" type = "string" />
        <argument name = "subject" type = "string" />
        <argument name = "content" type = "string" variadic = "1" />
        <return type = "integer" />
    </method>

    <method name = "sendforx">
        Send multipart string to service, end list with NULL
        Returns 0 if OK, -1 if failed due to lack of memory or other error.
        <argument name = "address" type = "string" />
        <argument name = "subject" type = "string" />
        <argument name = "content" type = "string" variadic = "1" />
        <return type = "integer" />
    </method>

    <method name = "recvx">
        Receive a subject and string content from the server. The content may be
        1 or more string frames. This method is orthogonal to the sendx methods.
        End the string arguments with NULL. If there are not enough frames in
        the received message, remaining strings are set to NULL. Returns number
        of string contents received, or -1 in case of error. Free the returned
        subject and content strings when finished with them. To get the type of
        the command, use mlm_client_command ().
        <argument name = "subject_p" type = "string" by_reference = "1" />
        <argument name = "string_p" type = "string" by_reference = "1" variadic = "1" />
        <return type = "integer" />
    </method>

    <method name = "set verbose">
        Enable verbose tracing (animation) of state machine activity.
        <argument name = "verbose" type = "boolean" />
    </method>
</class>