zyre.api

<class name = "zyre" state = "stable">
    <!--
    Copyright (c) the Contributors as noted in the AUTHORS file.

    This file is part of Zyre, an open-source framework for proximity-based
    peer-to-peer applications -- See http://zyre.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/.
    -->
    An open-source framework for proximity-based P2P apps

    <constructor>
        Constructor, creates a new Zyre node. Note that until you start the
        node it is silent and invisible to other nodes on the network.
        The node name is provided to other nodes during discovery. If you
        specify NULL, Zyre generates a randomized node name from the UUID.
        <argument name = "name" type = "string" optional = "1" />
    </constructor>

    <destructor>
        Destructor, destroys a Zyre node. When you destroy a node, any
        messages it is sending or receiving will be discarded.
    </destructor>

    <method name = "uuid">
        Return our node UUID string, after successful initialization
        <return type = "string" />
    </method>

    <method name = "name">
        Return our node name, after successful initialization. First 6
        characters of UUID by default.
        <return type = "string" />
    </method>

    <method name = "set name">
        Set the public name of this node overriding the default. The name is
        provide during discovery and come in each ENTER message.
        <argument name = "name" type = "string" />
    </method>

    <method name = "set header">
        Set node header; these are provided to other nodes during discovery
        and come in each ENTER message.
        <argument name = "name" type = "string" />
        <argument name = "format" type = "format" />
    </method>

    <method name = "set verbose">
        Set verbose mode; this tells the node to log all traffic as well as
        all major events.
    </method>

    <method name = "set port">
        Set UDP beacon discovery port; defaults to 5670, this call overrides
        that so you can create independent clusters on the same network, for
        e.g. development vs. production. Has no effect after zyre_start().
        <argument name = "port nbr" type = "integer" />
    </method>

    <method name = "set evasive timeout">
        Set the peer evasiveness timeout, in milliseconds. Default is 5000.
        This can be tuned in order to deal with expected network conditions
        and the response time expected by the application. This is tied to
        the beacon interval and rate of messages received.
        <argument name = "interval" type = "integer" />
    </method>

    <method name = "set expired timeout">
        Set the peer expiration timeout, in milliseconds. Default is 30000.
        This can be tuned in order to deal with expected network conditions
        and the response time expected by the application. This is tied to
        the beacon interval and rate of messages received.
        <argument name = "interval" type = "integer" />
    </method>

    <method name = "set interval">
        Set UDP beacon discovery interval, in milliseconds. Default is instant
        beacon exploration followed by pinging every 1,000 msecs.
        <argument name = "interval" type = "size" />
    </method>

    <method name = "set interface">
        Set network interface for UDP beacons. If you do not set this, CZMQ will
        choose an interface for you. On boxes with several interfaces you should
        specify which one you want to use, or strange things can happen.
        <argument name = "value" type = "string" />
    </method>

    <method name = "set endpoint">
        By default, Zyre binds to an ephemeral TCP port and broadcasts the local
        host name using UDP beaconing. When you call this method, Zyre will use
        gossip discovery instead of UDP beaconing. You MUST set-up the gossip
        service separately using zyre_gossip_bind() and _connect(). Note that the
        endpoint MUST be valid for both bind and connect operations. You can use
        inproc://, ipc://, or tcp:// transports (for tcp://, use an IP address
        that is meaningful to remote as well as local nodes). Returns 0 if
        the bind was successful, else -1.
        <argument name = "format" type = "format" />
        <return type = "integer" />
    </method>

    <method name = "set zcert" state = "draft">
        Apply a azcert to a Zyre node.
        <argument name = "zcert" type = "zcert"></argument>
    </method>

    <method name = "set zap domain" state = "draft">
        Specify the ZAP domain (for use with CURVE).
        <argument name = "domain" type = "string"/>
    </method>

    <method name = "gossip bind">
        Set-up gossip discovery of other nodes. At least one node in the cluster
        must bind to a well-known gossip endpoint, so other nodes can connect to
        it. Note that gossip endpoints are completely distinct from Zyre node
        endpoints, and should not overlap (they can use the same transport).
        <argument name = "format" type = "format" />
    </method>

    <method name = "gossip connect">
        Set-up gossip discovery of other nodes. A node may connect to multiple
        other nodes, for redundancy paths. For details of the gossip network
        design, see the CZMQ zgossip class.
        <argument name = "format" type = "format" />
    </method>

    <method name = "gossip connect curve" state = "draft">
        Set-up gossip discovery with CURVE enabled.
        <argument name = "public_key" type = "string" />
        <argument name = "format" type = "format" />
    </method>

    <method name = "start">
        Start node, after setting header values. When you start a node it
        begins discovery and connection. Returns 0 if OK, -1 if it wasn't
        possible to start the node.
        <return type = "integer" />
    </method>

    <method name = "stop">
        Stop node; this signals to other peers that this node will go away.
        This is polite; however you can also just destroy the node without
        stopping it.
    </method>

    <method name = "join">
        Join a named group; after joining a group you can send messages to
        the group and all Zyre nodes in that group will receive them.
        <argument name = "group" type = "string" />
        <return type = "integer" />
    </method>

    <method name = "leave">
        Leave a group
        <argument name = "group" type = "string" />
        <return type = "integer" />
    </method>

    <method name = "recv">
        Receive next message from network; the message may be a control
        message (ENTER, EXIT, JOIN, LEAVE) or data (WHISPER, SHOUT).
        Returns zmsg_t object, or NULL if interrupted
        <return type = "zmsg" fresh = "1" />
    </method>

    <method name = "whisper">
        Send message to single peer, specified as a UUID string
        Destroys message after sending
        <argument name = "peer" type = "string" />
        <argument name = "msg_p" type = "zmsg" by_reference = "1" />
        <return type = "integer" />
    </method>

    <method name = "shout">
        Send message to a named group
        Destroys message after sending
        <argument name = "group" type = "string" />
        <argument name = "msg_p" type = "zmsg" by_reference = "1" />
        <return type = "integer" />
    </method>

    <method name = "whispers">
        Send formatted string to a single peer specified as UUID string
        <argument name = "peer" type = "string" />
        <argument name = "format" type = "format" />
        <return type = "integer" />
    </method>

    <method name = "shouts">
        Send formatted string to a named group
        <argument name = "group" type = "string" />
        <argument name = "format" type = "format" />
        <return type = "integer" />
    </method>

    <method name = "peers">
        Return zlist of current peer ids.
        <return type = "zlist" fresh = "1" />
    </method>

    <method name = "peers by group">
        Return zlist of current peers of this group.
        <argument name = "name" type = "string" />
        <return type = "zlist" fresh = "1" />
    </method>

    <method name = "own groups">
        Return zlist of currently joined groups.
        <return type = "zlist" fresh = "1" />
    </method>

    <method name = "peer groups">
        Return zlist of groups known through connected peers.
        <return type = "zlist" fresh = "1" />
    </method>

    <method name = "peer address">
        Return the endpoint of a connected peer.
        <argument name = "peer" type = "string" />
        <return type = "string" fresh = "1" />
    </method>

    <method name = "peer header value">
        Return the value of a header of a conected peer.
        Returns null if peer or key doesn't exits.
        <argument name = "peer" type = "string" />
        <argument name = "name" type = "string" />
        <return type = "string" fresh = "1" />
    </method>

    <method name = "require peer" state = "draft">
        Explicitly connect to a peer
        <argument name = "uuid" type = "string" />
        <argument name = "endpoint" type = "string" />
        <argument name = "public_key" type = "string" optional = "1" />
        <return type = "integer" />
    </method>

    <method name = "socket">
        Return socket for talking to the Zyre node, for polling
        <return type = "zsock" />
    </method>

    <method name = "print">
        Print zyre node information to stdout
    </method>

    <method name = "version" singleton = "1">
        Return the Zyre version for run-time API detection; returns
        major * 10000 + minor * 100 + patch, as a single integer.
        <return type = "number" size = "8" />
    </method>
</class>