The ZMsg class implements a ZeroMQ message. More...

Public Member Methods
nothing	add (Qore::ZMQ::ZFrame frame)
	Pushes a frame to the end of the message; the frame is consumed by this call. More...

nothing	add (string str)
	Adds a string as a block of memory to the end of the message as a new frame. More...

nothing	add (binary bin)
	Adds a binary object to the end of the message as a new frame. More...

nothing	add (Qore::ZMQ::ZMsg submsg)
	Adds a message to the end of the message as a submessage; the message argument is consumed by this call. More...

	constructor (...)
	constructs a ZMsg from the arguments supplied More...

	constructor (list l)
	constructs a ZMsg from the list of arguments supplied More...

int	contentSize ()
	Returns the byte size of all frames in the message. More...

	copy ()
	copies a ZMsg object More...

ZFrame	encode ()
	Serializes a multipart message to a single message frame. More...

bool	eq (ZMsg msg2)
	Returns True if two msgs have identical size and data. More...

*string	meta (string property)
	Returns meta data property for the first frame in the message. More...

*binary	popBin (*string encoding)
	Pops the first frame off the front of message and returns it as a binary value. More...

*ZFrame	popFrame ()
	Removes and returns the first frame from the message, if any. More...

*ZMsg	popMsg ()
	Removes and returns the first submessage from message, if any. More...

*string	popStr (*string encoding)
	Pops the first frame off the front of message and returns it as a string. More...

nothing	print ()
	Sends a message to the zsys log sink (may be stdout, or system facility) More...

nothing	push (string str)
	Pushes a string as a block of memory to the beginning of the message as a new frame. More...

nothing	push (binary bin)
	Pushes a block of memory to the beginning of the message as a new frame. More...

nothing	push (Qore::ZMQ::ZFrame frame)
	Pushes a frame to the beginning of the message, i.e. before all other frames; the frame is consumed by this call. More...

int	routingId ()
	Returns a routing ID greater than 0 if the message is from a `SERVER` socket, 0 if not. More...

nothing	save (Qore::File file)
	Saves the message contents to an open file. More...

nothing	setRoutingId (int routing_id)
	Sets a routing ID on the message for use with `SERVER` sockets. More...

int	signal ()
	Returns the signal value, 0 or greater, if message is a signal, -1 if not. More...

int	size ()
	Returns the number of frames in the message. More...

Detailed Description

The ZMsg class implements a ZeroMQ message.

Note

In general, the ZMsg class is not designed to be accessed from multiple threads; it was created without locking for fast and efficient use when used from a single thread. For methods that would be unsafe to use in another thread, any use of such methods in threads other than the thread where the constructor was called will cause a ZMSG-THREAD-ERROR to be thrown.

Member Function Documentation

◆ add() [1/4]

nothing Qore::ZMQ::ZMsg::add ( Qore::ZMQ::ZFrame frame )

Pushes a frame to the end of the message; the frame is consumed by this call.

Example:: msg.add(frame);

Parameters

frame the frame to add to the end of the message; the argument object will be deleted by this call

Exceptions

ZMSG-APPEND-ERROR	this exception is thrown if any error occurs adding the frame to the message
ZMSG-THREAD-ERROR	this exception is thrown when the object is used in a thread other than the one that created it

◆ add() [2/4]

nothing Qore::ZMQ::ZMsg::add ( string str )

Adds a string as a block of memory to the end of the message as a new frame.

Example:: msg.add(str);

Parameters

str	the string to add to the end of the message

Exceptions

ZMSG-ADD-ERROR	this exception is thrown if any error occurs adding the frame to the message
ZMSG-THREAD-ERROR	this exception is thrown when the object is used in a thread other than the one that created it

◆ add() [3/4]

nothing Qore::ZMQ::ZMsg::add ( binary bin )

Adds a binary object to the end of the message as a new frame.

Example:: msg.add(bin);

Parameters

bin	the binary object to add to the end of the message

Exceptions

ZMSG-ADD-ERROR	this exception is thrown if any error occurs adding the frame to the message
ZMSG-THREAD-ERROR	this exception is thrown when the object is used in a thread other than the one that created it

◆ add() [4/4]

nothing Qore::ZMQ::ZMsg::add ( Qore::ZMQ::ZMsg submsg )

Adds a message to the end of the message as a submessage; the message argument is consumed by this call.

Example:: msg.add(msg);

Parameters

submsg the submessage to add to the end of the message; this object is deleted by this call

Exceptions

ZMSG-ADD-ERROR	this exception is thrown if any error occurs adding the submessage to the message
ZMSG-THREAD-ERROR	this exception is thrown when the object is used in a thread other than the one that created it

◆ constructor() [1/2]

Qore::ZMQ::ZMsg::constructor ( ... )

constructs a ZMsg from the arguments supplied

Example:: ZMsg msg(frame1, frame2);

Parameters

...

zero or more values to add to the message as frames; values are processed as follows:

ZFrame: the object is moved into the message, this call deletes the ZFrame object while processing
ZMsg: the object is moved into the message, this call deletes the ZMsg object while processing
string: copies the string data to the message
binary: copies the binary data to the message

Exceptions

ZMSG-ERROR unsupported data type passed as an argument

◆ constructor() [2/2]

Qore::ZMQ::ZMsg::constructor ( list l )

constructs a ZMsg from the list of arguments supplied

Example:: ZMsg msg(l);

Parameters

l

zero or more values to add to the message as frames; values are processed as follows:

ZFrame: the object is moved into the message, this call deletes the ZFrame object while processing
ZMsg: the object is moved into the message, this call deletes the ZMsg object while processing
string: copies the string data to the message
binary: copies the binary data to the message

Exceptions

ZMSG-ERROR unsupported data type passed as an argument

◆ contentSize()

int Qore::ZMQ::ZMsg::contentSize ( )

Returns the byte size of all frames in the message.

Code Flags:: CONSTANT

Example:: int size = msg.contentSize();

Exceptions

ZMSG-THREAD-ERROR this exception is thrown when the object is used in a thread other than the one that created it

See also: size()

◆ copy()

Qore::ZMQ::ZMsg::copy ( )

copies a ZMsg object

Example:: ZMsg msg_new = msg.copy();

Exceptions

ZMSG-THREAD-ERROR this exception is thrown when the object is used in a thread other than the one that created it

◆ encode()

ZFrame Qore::ZMQ::ZMsg::encode ( )

Serializes a multipart message to a single message frame.

Code Flags:: CONSTANT

Example:: ZFrame frm = msg.encode();

Use this method to send structured messages across transports that do not support multipart data. Creates a new ZFrame object containing the serialized message.

Exceptions

ZMSG-THREAD-ERROR this exception is thrown when the object is used in a thread other than the one that created it

See also: ZFrame::decode()

◆ eq()

bool Qore::ZMQ::ZMsg::eq ( ZMsg msg2 )

Returns True if two msgs have identical size and data.

Code Flags:: CONSTANT

Example:: bool b = msg.more();

Parameters

msg2	the message to compare

Returns: True if two msgs have identical size and data

Exceptions

ZMSG-THREAD-ERROR this exception is thrown when the object is used in a thread other than the one that created it

◆ meta()

*string Qore::ZMQ::ZMsg::meta ( string property )

Returns meta data property for the first frame in the message.

Code Flags:: CONSTANT

Example: *string str = msg.meta("Socket-Type");

Parameters

property

a meta-data property for the first frame in the message; the string is converted to UTF-8 encoding if necessary; the following properties are available:

"Socket-Type":
"Identity":
"Resource":
"Peer-Address" if supported by the undelying transport; this property will return the IP address of the remote endpoint as returned by getnameinfo(2).

Returns: a string in UTF-8 encoding giving the property value or nothing if no such property is set for the frame

Exceptions

MISSING-FEATURE-ERROR	thrown if the underlying czmq library is missing the `zframe_meta()` function; check HAVE_ZFRAME_META before calling this method
ENCODING-CONVERSION-ERROR	this exception could be thrown if an encoding error is encountered when converting the given string to UTF-8

Note

the input string is converted to UTF-8 encoding if necessary
Other properties may be defined based on the underlying security mechanism
only available if the underlying library supports it; check HAVE_ZFRAME_META before calling this method

◆ popBin()

*binary Qore::ZMQ::ZMsg::popBin ( *string encoding )

Pops the first frame off the front of message and returns it as a binary value.

Example:: *binary str = msg.popBin();

Returns: a binary value corresponding to the first frame which is removed from the message; if no frame is present nothing is returned

Exceptions

ZMSG-THREAD-ERROR this exception is thrown when the object is used in a thread other than the one that created it

◆ popFrame()

*ZFrame Qore::ZMQ::ZMsg::popFrame ( )

Removes and returns the first frame from the message, if any.

Example:: *ZFrame frame = msg.popFrame();

Returns: the first frame from the message, if any; if no frame is present, nothing is returned

Exceptions

ZMSG-THREAD-ERROR this exception is thrown when the object is used in a thread other than the one that created it

◆ popMsg()

*ZMsg Qore::ZMQ::ZMsg::popMsg ( )

Removes and returns the first submessage from message, if any.

Example:: *ZFrame msg = msg.popMsg();

Returns: the first submessage from the message, if any; if the first frame is not a submessage or the message contains no frames, nothing is returned

Exceptions

ZMSG-THREAD-ERROR this exception is thrown when the object is used in a thread other than the one that created it

Note: this call consumes the first frame whether it's a submessage or not

◆ popStr()

*string Qore::ZMQ::ZMsg::popStr ( *string encoding )

Pops the first frame off the front of message and returns it as a string.

Example:: *string str = msg.popStr();

Parameters

encoding the character encoding tag for the string return value; if not present, the default character encoding is assumed.

Returns: a string corresponding to the first frame which is removed from the message; if no frame is present nothing is returned

Exceptions

ZMSG-THREAD-ERROR this exception is thrown when the object is used in a thread other than the one that created it

◆ print()

nothing Qore::ZMQ::ZMsg::print ( )

Sends a message to the zsys log sink (may be stdout, or system facility)

Example:: msg.print();

Exceptions

ZMSG-THREAD-ERROR this exception is thrown when the object is used in a thread other than the one that created it

◆ push() [1/3]

nothing Qore::ZMQ::ZMsg::push ( string str )

Pushes a string as a block of memory to the beginning of the message as a new frame.

Example:: msg.push(str);

Parameters

the	string to add to the beginning of the message

Exceptions

ZMSG-PUSH-ERROR	this exception is thrown if any error occurs adding the frame to the message
ZMSG-THREAD-ERROR	this exception is thrown when the object is used in a thread other than the one that created it

◆ push() [2/3]

nothing Qore::ZMQ::ZMsg::push ( binary bin )

Pushes a block of memory to the beginning of the message as a new frame.

Example:: msg.push(bin);

Parameters

the	string to add to the beginning of the message

Exceptions

ZMSG-PUSH-ERROR	this exception is thrown if any error occurs adding the frame to the message
ZMSG-THREAD-ERROR	this exception is thrown when the object is used in a thread other than the one that created it

◆ push() [3/3]

nothing Qore::ZMQ::ZMsg::push ( Qore::ZMQ::ZFrame frame )

Pushes a frame to the beginning of the message, i.e. before all other frames; the frame is consumed by this call.

Example:: msg.push(frame);

Parameters

frame the frame to add to the beginning of the message; the argument object will be deleted by this call

Exceptions

ZMSG-PREPEND-ERROR	this exception is thrown if any error occurs prepending the frame to the message
ZMSG-THREAD-ERROR	this exception is thrown when the object is used in a thread other than the one that created it

◆ routingId()

int Qore::ZMQ::ZMsg::routingId ( )

Returns a routing ID greater than 0 if the message is from a SERVER socket, 0 if not.

Code Flags:: CONSTANT

Example:: int routing_id = msg.routingId();

Returns: a routing ID greater than 0 if the message is from a SERVER socket, 0 if not

Exceptions

MISSING-FEATURE-ERROR thrown if the underlying czmq library is missing draft APIs; check HAVE_ZMQ_DRAFT_APIS before calling this method

Note

only available if the underlying library supports it; check HAVE_ZMQ_DRAFT_APIS before calling this method

◆ save()

nothing Qore::ZMQ::ZMsg::save ( Qore::File file )

Saves the message contents to an open file.

Example:: File f();
f.open(file_name, O_CREAT|O_WRONLY|O_TRUNC);
msg.save(f);

Parameters

file	the file to save the data to; must be open for writing

The message is saved as a series of frames, each with length and data.

Exceptions

ZMSG-THREAD-ERROR	this exception is thrown when the object is used in a thread other than the one that created it
ZMSG-SAVE-ERROR	if there is any error saving the data, this exception is thrown

Note: The file is NOT guaranteed to be portable between operating systems, not versions of CZMQ. The file format is at present undocumented and liable to arbitrary change.

◆ setRoutingId()

nothing Qore::ZMQ::ZMsg::setRoutingId ( int routing_id )

Sets a routing ID on the message for use with SERVER sockets.

Example:: msg.setRoutingId(routing_id);

Parameters

routing_id a routing ID for the message

Exceptions

MISSING-FEATURE-ERROR thrown if the underlying czmq library is missing draft APIs; check HAVE_ZMQ_DRAFT_APIS before calling this method

Note

only available if the underlying library supports it; check HAVE_ZMQ_DRAFT_APIS before calling this method

◆ signal()

int Qore::ZMQ::ZMsg::signal ( )

Returns the signal value, 0 or greater, if message is a signal, -1 if not.

Code Flags:: CONSTANT

Example:: int size = msg.signal();

Exceptions

ZMSG-THREAD-ERROR this exception is thrown when the object is used in a thread other than the one that created it

◆ size()

int Qore::ZMQ::ZMsg::size ( )

Returns the number of frames in the message.

Code Flags:: CONSTANT

Example:: int size = msg.size();

Exceptions

ZMSG-THREAD-ERROR this exception is thrown when the object is used in a thread other than the one that created it

See also: contentSize()

The documentation for this class was generated from the following file:

QC_ZMsg.dox.h

Public Member Methods

Detailed Description

Member Function Documentation

◆ add() [1/4]

◆ add() [2/4]

◆ add() [3/4]

◆ add() [4/4]

◆ constructor() [1/2]

◆ constructor() [2/2]

◆ contentSize()

◆ copy()

◆ encode()

◆ eq()

◆ meta()

◆ popBin()

◆ popFrame()

◆ popMsg()

◆ popStr()

◆ print()

◆ push() [1/3]

◆ push() [2/3]

◆ push() [3/3]

◆ routingId()

◆ save()

◆ setRoutingId()

◆ signal()

◆ size()