zmq_msg_gets.txt 2.34 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11
zmq_msg_gets(3)
===============


NAME
----
zmq_msg_gets - get message metadata property


SYNOPSIS
--------
12
*const char *zmq_msg_gets (zmq_msg_t '*message', const char *'property');*
13 14 15 16 17 18


DESCRIPTION
-----------
The _zmq_msg_gets()_ function shall return the string value for the metadata
property specified by the 'property' argument for the message pointed to by
19 20
the 'message' argument. Both the 'property' argument and the 'value'
shall be NULL-terminated UTF8-encoded strings.
21

22
Metadata is defined on a per-connection basis during the ZeroMQ connection
23 24 25
handshake as specified in <rfc.zeromq.org/spec:37>. Applications can set
metadata properties using linkzmq:zmq_setsockopt[3] option ZMQ_METADATA.
Application metadata properties must be prefixed with 'X-'.
26

27 28
In addition to application metadata, the following ZMTP properties can be
retrieved with the _zmq_msg_gets()_ function:
29 30

    Socket-Type
31 32 33
    Routing-Id

Note: 'Identity' is a deprecated alias for 'Routing-Id'.
34 35 36 37

Additionally, when available for the underlying transport, the *Peer-Address*
property will return the IP address of the remote endpoint as returned by
getnameinfo(2).
38

39
The names of these properties are also defined in _zmq.h_ as
40
_ZMQ_MSG_PROPERTY_SOCKET_TYPE_ _ZMQ_MSG_PROPERTY_ROUTING_ID_, and 
41 42 43
_ZMQ_MSG_PROPERTY_PEER_ADDRESS_.
Currently, these definitions are only available as a DRAFT API.

44
Other properties may be defined based on the underlying security mechanism,
45
see ZAP authenticated connection sample below.
46 47 48 49 50 51

RETURN VALUE
------------
The _zmq_msg_gets()_ function shall return the string value for the property
if successful. Otherwise it shall return NULL and set 'errno' to one of the
values defined below. The caller shall not modify or free the returned value,
52 53
which shall be owned by the message. The encoding of the property and value
shall be UTF8.
54 55 56 57 58 59 60 61 62 63


ERRORS
------
*EINVAL*::
The requested _property_ is unknown.


EXAMPLE
-------
Pieter Hintjens's avatar
Pieter Hintjens committed
64
.Getting the ZAP authenticated user id for a message:
65
----
Pieter Hintjens's avatar
Pieter Hintjens committed
66 67 68 69
zmq_msg_t msg;
zmq_msg_init (&msg);
rc = zmq_msg_recv (&msg, dealer, 0);
assert (rc != -1);
70
const char *user_id = zmq_msg_gets (&msg, ZMQ_MSG_PROPERTY_USER_ID);
Pieter Hintjens's avatar
Pieter Hintjens committed
71
zmq_msg_close (&msg);
72 73 74 75 76 77
----


SEE ALSO
--------
linkzmq:zmq[7]
78
linkzmq:zmq_setsockopt[3]
79 80 81 82 83

AUTHORS
-------
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.