jzmqConnection Class Reference

Inheritance diagram for jzmqConnection:

Public Types
enum	Events { time }
	poll socket to identify whether we can send ('out') or receive ('in') More...

Public Member Functions
function	jzmqConnection (in varargin)
function	open (in me, in context)
	Class constructor for jzmqConnection.
function	poll (in me, in events, in time)
	Opens the ØMQ socket connection.
function	sendCommand (in me, in command, in data, in getReply)
function	receiveCommand (in me, in sendReply)
	Sends a command and optional data, then waits for a reply.
function	flush (in me)
	Receives a command and associated data, optionally sending an 'ok' reply.
function	get (in me, in option)
	Flushes the receive buffer of the socket.
function	set (in me, in option, in value)
	Gets the value of a ØMQ socket option.
function	send (in me, in data)
	Sets the value of a ØMQ socket option.
function	receive (in me)
	Sends raw data over the socket.
function	close (in me, in keepContext)
	Receives raw data from the socket.
function	delete (in me)
	Closes the ØMQ socket and optionally the context.
function get	endpoint (in me)
	Class destructor.
function set	type (in me, in value)
	Gets the full endpoint string for the connection.
function	sendObject (in me, in command, in data, in useJSON)
	Sets the socket type.
function	receiveObject (in me, in useJSON, in options)
	(Private) Sends a command string and optional serialized MATLAB data.
function	sendViaProxy (in me, in command, in data, in proxy)
	(Private) Receives a command string and optional serialized MATLAB data.
Public Member Functions inherited from optickaCore
function	optickaCore (in varargin)
	Class constructor.
function get	fullName (in me)
function	getALF (in me, in subject, in lab, in create)
	get the ALF path
function	makeReport (in me, in rpt)
	Generate a detailed report for the opticka object.
function	findAttributes (in me, in attrName, in attrValue)
function	findAttributesandType (in me, in attrName, in attrValue, in type)
	find properties of object with specific attributes, for example all properties whose GetAcccess attribute is public and type is logical.
function	findPropertyDefault (in me, in propName)
	Return the declared default value for a class property.
function	clone (in me)
	Use this syntax to make a deep copy of the object, i.e. OBJ_OUT has the same field values, but will not behave as a handle-copy of me anymore.
function	checkSuperclasses (in List)
function	editProperties (in me, in properties)
	method to modify a set of properties
function	setProp (in me, in property, in value)
	method to fast change a particular value. This is useful for use in anonymous functions, like in the state machine.
function	initialiseSaveFile (in me, in varargin)
	just get date fragment for backwards compatibility
function	checkPaths (in me)
	checks the paths are valid

Public Attributes
Property	type
	ØMQ connection type, e.g. 'REQ', 'REP', 'PUB', 'SUB', etc.
Property	transport
	transport for the socket, tcp | ipc | inproc
Property	address
	the address to open, use * for a server to bind to all interfaces
Property	port
	the port to open
Property	frameSize
	default size of chunk to read/write for tcp
Property	readTimeOut
	default read timeout in ms, -1 is blocking
Property	writeTimeOut
	default write timeout in ms, -1 is blocking
Property	verbose
	do we log to the command window?
Property	alwaysPoll
	for sendCommand and receiveCommand use zmq.core.poll?
Property	httpProxy
	use a http proxy to send message
Property	endpoint
	connection endpoint
Public Attributes inherited from optickaCore
Property	name
	object name
Property	comment
	comment
Property	verbose
	verbose logging, subclasses must assign this. This is normally logical true/false
Property	optickaVersion
	version number
Property	dateStamp
	clock() dateStamp set on construction
Property	uuid
	universal ID
Property	paths
	storage of various paths
Property	fullName
	The fullName is the object name combined with its uuid and class name.

Additional Inherited Members
Static Public Member Functions inherited from optickaCore
static function	initialiseGlobals (in doReset, in doOpen)
static function	makeArgs (in args)
	Converts cell args to structure array.
static function	addDefaults (in args, in defs)
	regularises and adds default options to arg input
static function	hasKey (in in, in key)
	check if a struct / object has a propery / field
static function	getKeys (in device)
	PTB Get key presses, stops key bouncing.
Protected Member Functions inherited from optickaCore
function	parseArgs (in me, in args, in allowedProperties)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.
function	addArgs (in me, in args)
function	setPaths (in me)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.
function	getFonts (in me)
	set paths for object
function	toStructure (in me)
	Converts properties to a structure.
function	getType (in me, in in)
function	logOutput (in me, in in, in message, in override)
	Give a metaproperty return the likely property class.
function	salutation (in me, in varargin)
	Prints messages dependent on verbosity.
Protected Attributes inherited from optickaCore
Property	cloning
	are we cloning this from another object
Property	mversion
	Matlab version number, this is transient so it is not saved.
Property	sansFont
	sans font
Property	monoFont
	monoFont
Property	className
	class name
Property	savePrefix
	save prefix generated from clock time
Property	fullName_
	cached full name

Member Enumeration Documentation

Events

enum jzmqConnection::Events

poll socket to identify whether we can send ('out') or receive ('in')

Parameters

events	string 'in' 'out' or 'both'
time	in ms, 0 = no wait, -1 = block until response

Enumerator
time

                                                   {}; end
            if nargin < 2 || isempty(command); error('You must pass a command!'); end
            try
                [status, nbytes, msg] = sendObject(me, command, data, true);
                if status ~= 0
                    warning(msg);
                end
            catch ME
                t = sprintf('Receive status %i did not return any command: %s - %s...\n', status, ME.identifier, ME.message);
                me.addMessage(t);
                disp(t);
            end
            if status == 0 && getReply
                [rep, dataOut, ~, t] = receiveObject(me);
                if ~isempty(t); me.addMessage(t); end
                if me.verbose
                    disp(t);
                    disp(dataOut);
                end
            end
        end
 
        % ===================================================================
        function [command, data, msg] = receiveCommand(me, sendReply)
        %> @brief Receives a command and associated data, optionally sending an 'ok' reply.
        %> @details Calls `receiveObject` to get the command string and any
        %>   serialized data. If `sendReply` is true (default) and a command was
        %>   successfully received, it sends back an 'ok' command using `sendObject`.
        %> @param sendReply (Optional) Logical flag. If true (default), sends an
        %>   'ok' reply upon successful receipt of a command. If false, no reply
        %>   is sent by this function. Defaults to true.
        %> @return command The received command string. Empty if receive failed or timed out.
        %> @return data The deserialized MATLAB data received with the command. Empty if no data part or on error.
        % ===================================================================
            command = ''; data = []; msg = '';
            if ~me.isOpen; return; end
            if nargin < 2
                sendReply = true; % Default behavior: send 'ok' reply
            end
            try
                [command, data, msg] = receiveObject(me, true);
                if isempty(command) && ~isempty(msg)
                    msg = sprintf('Receive problem: %s', msg); % Log if receiveObject reported an issue
                    me.addMessage(msg);
                    warning(msg)
                elseif ~isempty(command)
                    if me.verbose 
                        fprintf('Received command: «%s»\n', command);
                        if ~isempty(data)
                            disp('Received data:');
                            disp(data);
                        end
                    end
                end
            catch ME
                fprintf('Error during receiveCommand: cmd: %s msg: %s err: %s - %s\n', command, msg, ME.identifier, ME.message);
                command = ''; data = []; % Ensure empty return on error
                return % Exit function on critical error
            end
            
            % Send 'ok' reply only if requested and a command was actually received
            if sendReply && ~isempty(command)
                status = sendObject(me, 'ok', {});
                if status ~= 0
                    msg = sprintf('Default "ok" reply failed to be sent for command "%s"', command);
                    me.addMessage(msg);
                    warning(msg);
                    me.sendState = false; % Update state on send failure
                end
            elseif ~isempty(command)
                % If reply is not sent here, the caller is responsible.
            end
        end
 
        % ===================================================================
        function flush(me)
        %> @brief Flushes the receive buffer of the socket.
        %> @details Temporarily sets the receive timeout (`ReceiveTimeOut`) to 0 (non-blocking)
        %>   and enters a loop calling `receive` until it returns a status of -1
        %>   (indicating no more messages or an error). It then restores the
        %>   original `readTimeOut`. This is useful for discarding any pending
        %>   messages in the socket's incoming queue.
        % ===================================================================
            try
                me.set('ReceiveTimeOut', 0);
                N = 1000;
                while N > 0
                    status = 0;
                    if verifyEvent('in'); [~, status] = receive(me); end
                    if status == -1; N = 0; end
                end
            catch ME
                if me.verbose; fprintf('Flush error: %s %s', ME.identifier, ME.message); end
            end
            me.set('ReceiveTimeOut', me.readTimeOut);
        end
 
        % ===================================================================
        function value = get(me, option)
        %> @brief Gets the value of a ØMQ socket option.
        %> @details A wrapper around the `zmq.Socket.get` method.
        %> @param option The name of the socket option to retrieve (e.g., 'Linger', 'ReceiveTimeOut').
        %>   Case-insensitive, 'ZMQ_' prefix is optional.
        %> @return value The current value of the specified socket option.
        %> @warning Issues a warning if `option` is not provided.
        % ===================================================================
            arguments (Input)
                me
                option string {mustBeMember(option,...
                    ["Linger","ReceiveBufferSize",...
                    "SendBufferSize","HWM",...
                    "ReceiveTimeOut","SendTimeOut",...
                    "SocketType","Type","Ctx"])}
            end
            arguments (Output)
                value
            end
            value = me.socket.pointer.("get" + option);
        end
 
        % ===================================================================
        function status = set(me, option, value)
        %> @brief Sets the value of a ØMQ socket option.
        %> @details A wrapper around the `zmq.Socket.set` method.
        %> @param option The name of the socket option to set (e.g., 'ReceiveTimeOut', 'LINGER').
        %>   Case-insensitive, 'ZMQ_' prefix is optional.
        %> @param value The value to assign to the socket option.
        %> @return status 0 on success, non-zero on failure.
        %> @warning Issues warnings if `option` or `value` are not provided.
        % ===================================================================
            arguments (Input)
                me
                option string {mustBeMember(option,...
                    ["Linger","ReceiveBufferSize",...
                    "SendBufferSize","HWM",...
                    "ReceiveTimeOut","SendTimeOut",...
                    "SocketType","Type","Ctx"])}
                value
            end
            arguments (Output)
                status
            end
            status = me.socket.pointer.("set" + option)(value);
            if ~status
                warning('zmqConnection:set:failure','Failed to set %s', option)
            end
        end
 
        % ===================================================================
        function status = send(me, data)
        %> @brief Sends raw data over the socket.
        %> @details Determines the type of data and calls the appropriate
        %>   `zmq.Socket` send method (`send_string` for char/string, `send` for
        %>   uint8). If the data type is different, it attempts to use the
        %>   private `sendObject` method (which might not be intended for raw data).
        %> @param data The data to send. Can be a character array, string, or uint8 array.
        %> @return status 0 on success, -1 on failure (e.g., timeout, incorrect socket state).
        % ===================================================================
            try
                status = [];
                if ischar(data) || isstring(data)
                    result = me.socket.send(uint8(data));
                elseif isa(data,'uint8')
                    result = me.socket.send(data);
                else
                    result = sendObject(me, data);
                end
                if result; status = 0; end
            catch ME
                status = -1;
                t = sprintf('Couldn''t send, perhaps need to receive first: %s - %s', ME.identifier, ME.message);
                me.addMessage(t);
                warning(t);
            end
        end
 
        % ===================================================================
        function [data, status] = receive(me)
        %> @brief Receives raw data from the socket.
        %> @details Calls `zmq.Socket.recv_multipart` to receive data. If the
        %>   result is a single-element cell array, it extracts the content.
        %> @return data The received data, typically as a uint8 array or potentially
        %>   a cell array for true multipart messages. Empty on failure or timeout.
        %> @return status 0 on success (implied, not explicitly returned on success),
        %>   -1 on failure (e.g., timeout).
        % ===================================================================
            data = []; status = -1;
            try
                data = me.receiveMultipart();
                if iscell(data) && isscalar(data)
                    data = data{:};
                end
                status = 0;
            catch ME
                t = sprintf('No data received: %s - %s...\n', ME.identifier, ME.message);
                me.addMessage(t);
                if me.verbose; disp(t); end
            end
        end
 
        % ===================================================================
        function close(me, keepContext)
        %> @brief Closes the ØMQ socket and optionally the context.
        %> @details Closes the underlying `zmq.Socket` if it's open. If
        %>   `keepContext` is false (default), it also closes the `zmq.Context`.
        %>   Sets the `isOpen` flag to false.
        %> @param keepContext (Optional) Logical flag. If true, the ØMQ context
        %>   is kept open; otherwise (default), the context is also closed.
        %>   Defaults to false.
        %> @note Uses `try...end` blocks to suppress errors during closure.
        % ===================================================================
            if ~exist('keepContext','var'); keepContext = false; end
            
            try me.socket.close(); me.socket = []; end %#ok<*TRYNC>
            try me.poller.close(); me.poller = []; end %#ok<*TRYNC>
 
            if ~keepContext
                me.context = [];
            end
    
            me.isOpen = false;
        end
        function delete(me)
        %> @brief Class destructor.
        %> @details Ensures the socket and context are closed by calling `close(me, false)`
        %>   when the object is destroyed.
        % ===================================================================
            close(me, false);
        end
 
        % ===================================================================
        function endpoint = get.endpoint(me)
        %> @brief Gets the full endpoint string for the connection.
        %> @details Constructs the endpoint string (e.g., 'tcp://localhost:5555')
        %>   based on the `transport`, `address`, and `port` properties.
        %> @return endpoint The formatted endpoint string.
        % ===================================================================
            endpoint = sprintf('%s://%s:%i',me.transport,me.address,me.port);
        end
 
        % ===================================================================
        function set.type(me, value)
        %> @brief Sets the socket type.
        %> @details Validates the socket type against a list of allowed types
        %>   and sets the `type` property. Throws an error if the type is invalid.
        %> @param value The socket type to set (e.g., 'REQ', 'REP', 'PUB', 'SUB').
        %> @note Uses SocketType enum, defaults to 'REQ'.
        % ===================================================================
            arguments
                me jzmqConnection
                value (1,1) jzmq.SocketType
            end
 
            try
                me.type = value;
            catch
                me.type = 'REQ';
                warning('Invalid socket type. Defaulting to REQ.');
            end
        end
 
        % ===================================================================
        function [status, nbytes, msg] = sendObject(me, command, data, useJSON)
        %> @brief (Private) Sends a command string and optional serialized MATLAB data.
        %> @details This is the core sending method used by public methods like
        %>   `sendCommand` and `receiveCommand` (for replies). It checks if the
        %>   socket is open, validates the command is a string, serializes the
        %>   `data` using `getByteStreamFromArray` (if provided), and sends the
        %>   command and data as a two-part message using `zmq.Socket.send` with
        %>   the 'sndmore' flag if both parts exist. Handles sending only command,
        %>   only data, or an empty message if both are empty.
        %> @param command The command string to send. Must be char or string.
        %> 
        %> @param data (Optional) MATLAB data to serialize and send.
        %> @param useJSON (optional) wrap command and data with JSON
        %>
        %> @return status 0 on success, -1 on failure.
        %> @return nbytes The total number of bytes sent across all parts.
        %> @return msg An error message string if `status` is -1.
        % ===================================================================
            
            status = -1; nbytes = 0; msg = '';
        
            % Check if the socket is open
            if ~me.isOpen
                error('Socket is not open. Please open the socket before sending data.');
            end
 
            % Check if the command is a string
            if ~exist('command','var') || ~ischar(command) && ~isstring(command)
                error('Command must be a string or character array.');
            end
 
            if nargin < 5
                options = {};
            end
 
            if nargin < 4 || isempty(useJSON)
                useJSON = true;
            end
 
            if nargin < 3
                data = [];
            end
        
            % Serialize the object if it's not empty
            if ~isempty(data)
                serialData = getByteStreamFromArray(data);
            else
                % If no data, just send an empty array
                serialData = uint8([]);
            end
 
            try
                if useJSON
                    j.command = command;
                    j.dataType = 'byteStream';
                    j.data = serialData;
                    j = jsonencode(j);
                    b = unicode2native(j, 'UTF-8');
                    nbytes = me.socket.send(uint8(b), options{:});
                elseif ~isempty(command) && ~isempty(serialData)
                    n1 = me.socket.send(uint8(command), 'sndmore');
                    n2 = me.socket.send(serialData, options{:});
                    nbytes = n1 + n2;
                elseif ~isempty(command)
                    % Just send text
                    nbytes = me.socket.send(uint8(command), options{:});
                elseif ~isempty(serialData)
                    % Just send data
                    nbytes = me.socket.send(serialData, options{:});
                else
                    % Send empty message
                    nbytes = me.socket.send(uint8(''), options{:});
                end
                status = 0;
            catch ME
                status = -1;
                msg = [ME.identifier, ME.message];
            end
        end
        
        % ===================================================================
        function [command, data, raw, msg] = receiveObject(me, useJSON, options)
        %> @brief (Private) Receives a command string and optional serialized MATLAB data.
        %> @details This is the core receiving method. It calls `zmq.Socket.recv`
        %>   to get the first part (expected to be the command string). It checks
        %>   the 'rcvmore' socket option to see if a second part (data) exists.
        %>   If so, it calls `zmq.Socket.recv_multipart` to get the remaining part(s),
        %>   concatenates them if necessary, and deserializes the result using
        %>   `getArrayFromByteStream`.
        %> @param options (Optional) Cell array of flags for the initial `recv` call (e.g., {'ZMQ_DONTWAIT'}).
        %> @return command The received command string. Empty on failure or timeout.
        %> @return data The deserialized MATLAB data. Empty if no data part, deserialization fails, or on error.
        %> @return raw the original structure
        %> @return msg An error message string if receiving the command failed or deserialization failed.
        %> @note This is a private method. Throws an error if the socket is not open. Logs deserialization errors.
        % ===================================================================
            % Check if the socket is open
            if ~me.isOpen
                error('Socket is not open. Please open the socket before sending data.');
            end
 
            if nargin < 3; options = {}; end
 
            if nargin < 2 || isempty(useJSON); useJSON = true; end
 
            command = ''; data = []; msg = ''; raw = []; frames = {};
 
            try
                frames = me.receiveMultipart();
            catch ME
                warning('Failed to get object: %s - %s', ME.identifier, ME.message);
                if matches(ME.identifier,'zmq:core:recv:EFSM')
                    t = sprintf('EFSM error, let''s try to flush and send');
                    me.addMessage(t);
                    if me.verbose; disp(t); end
                    me.flush;
                    me.sendObject('error',{''});
                end
            end
            if isempty(frames); return; end
 
            if useJSON
                try
                    if iscell(frames)
                        str = native2unicode([frames{1:end}], 'UTF-8');
                    else
                        str = native2unicode(frames, 'UTF-8');
                    end
                    src = jsondecode(str);
                    if isstruct(src)
                        command = src.command;
                        if isfield(src,'data') && ~isempty(src.data)
                            data = getArrayFromByteStream(uint8(src.data));
                        end
                    end
                    raw = src;
                catch ME
                    msg = 'Cannot parse JSON...';
                    me.addMessage(msg);
                    getReport(ME)
                    return
                end
            else
                command = frames{1};
                if command == -1 
                    msg = 'No data received...';
                    me.addMessage(msg);
                    command = '';
                    return
                end
                command = char(command);
                if length(frames) > 1
                    data = frames{2:end};
                    if iscell(data)
                        data = [data{:}];
                    end
                    % Deserialize the object if it's not empty
                    if ~isempty(data)
                        try
                            data = getArrayFromByteStream(data);
                        catch ME
                            msg = sprintf('Failed to deserialize object: %s - %s', ME.identifier, ME.message);
                            me.addMessage(msg);
                            warning(msg);
                            data = [];
                        end
                    else
                        data = [];
                    end
                else
                    % No object part in the message
                    data = [];
                end
            end
        end
 
 
        % ===================================================================
        function [response, dataOut] = sendViaProxy(me, command, data, proxy)
        %> @brief sendViaProxy - Sends data to a specified URL via a proxy
        %>
        %> This function sends the provided data to the specified URL using
        %> a proxy server and returns the server's response.
        %>
        %> @param command   A string specifying the command to be sent
        %> @param data  A MATLAB object containing the data to be sent in the request.
        %>
        %> @return response  The response from the server after sending the data.
        % ===================================================================
            arguments(Input)
                me jzmqConnection
                command string = 'echo'
                data = []
                proxy string = me.httpProxy
            end
            arguments(Output)
                response struct
                dataOut
            end
            response = []; dataOut = [];
            opts = weboptions('TimeOut',2,'MediaType', 'application/json', 'ContentType', 'json', 'CharacterEncoding', 'UTF-8');
            data = getByteStreamFromArray(data);
            dataStruct = struct('command',command,'dataType','byteStream','data', data);
            try
                response = webwrite(proxy, dataStruct, opts);
                fprintf('sendViaProxy send: "%s" - respone: \n%s\n', command, jsonencode(response));
                if isstruct(response) && isfield(response,'dataType') && matches(response.dataType,'byteStream')
                    try dataOut = getArrayFromByteStream(uint8(response.data)); end
                    if ~isempty(dataOut)
                        disp(dataOut);
                    end
                end
            catch ME
                response = struct('error',string(ME.identifier));
                dataOut = struct('error',string(ME.identifier),'data', ME.message,'cause','Ensure cogmoteGO and theConductor are running!!!');
                warning('sendViaProxy: "%s" failed - error: %s -  %s\n', command, ME.identifier, ME.message);
            end
        end
        
    end
 
    methods (Access = private)
 
        % ===================================================================
        %> @brief Receives all parts of a multipart message from the socket.
        %> @details Calls `recv` on the socket to get the first part, then
        %>   continues calling `recv` while `hasReceiveMore` is true, collecting
        %>   all parts into a cell array. If only one part is received, returns
        %>   it directly.
        %> @return data Cell array of message parts, or the single part if only one.
        % ===================================================================
        function data = receiveMultipart(me)
            data = {};
            data{1} = me.socket.recv();
            a = 2;
            while me.socket.hasReceiveMore()
                data{a} = me.socket.recv();
            end
            if iscell(data) && isscalar(data)
                data = data{:};
            end
        end
 
        % ===================================================================
        %> @brief Adds a message to the object's message log.
        %> @details Converts the input `msg` to a string if necessary, then
        %>   appends it to the `messages` property. Handles struct, object,
        %>   char, and string types. If `msg` is empty or not provided, does nothing.
        %> @param msg The message to add (struct, object, char, string, or array).
        % ===================================================================
        function addMessage(me, msg)
            if nargin < 2; return; end
            if isstruct(msg) || isobject(msg)
                msg = formattedDisplayText(msg,"NumericFormat","short","LineSpacing","compact");
            elseif ischar(msg)
                msg = string(msg);
            elseif length(msg) > 1
                msg = join(msg);
            else
                return;
            end
            if isempty(me.messages)
                me.messages(1) = msg;
            else
                me.messages(end+1) = msg;
            end
        end
        
        % ===================================================================
        %> @brief Checks if the socket is ready for the specified event(s).
        %> @details Uses polling to determine if the socket can send ('out'),
        %>   receive ('in'), or neither ('none'). If `alwaysPoll` is false,
        %>   always returns true.
        %> @param events String: 'in', 'out', or 'none'.
        %> @return out Logical true if the event is ready, false otherwise.
        % ===================================================================
        function out = verifyEvent(me, events)
            if ~me.alwaysPoll; out = true; return; end
            out = false;
            r = poll(me,'both',0);
            switch events
                case 'in'
                    if matches(r,{'in','both'}) 
                        out = true; 
                    end
                case 'out'
                    if matches(r,{'out','both'})
                        out = true; 
                    end
                case 'none'
                    if matches(r,'none')
                        out = true;
                    end
            end
        end
    end
end

Constructor & Destructor Documentation

jzmqConnection()

function jzmqConnection::jzmqConnection

(

in

varargin

)

Member Function Documentation

close()

function jzmqConnection::close	(	in	me,
		in	keepContext
	)

Receives raw data from the socket.

Calls zmq.Socket.recv_multipart to receive data. If the result is a single-element cell array, it extracts the content.

Returns

data The received data, typically as a uint8 array or potentially a cell array for true multipart messages. Empty on failure or timeout.

status 0 on success (implied, not explicitly returned on success), -1 on failure (e.g., timeout).

delete()

function jzmqConnection::delete

(

in

me

)

Closes the ØMQ socket and optionally the context.

Closes the underlying zmq.Socket if it's open. If keepContext is false (default), it also closes the zmq.Context. Sets the isOpen flag to false.

Parameters

keepContext

(Optional) Logical flag. If true, the ØMQ context is kept open; otherwise (default), the context is also closed. Defaults to false.

Note

Uses try...end blocks to suppress errors during closure.

endpoint()

function get jzmqConnection::endpoint

(

in

me

)

Class destructor.

Ensures the socket and context are closed by calling close(me, false) when the object is destroyed.

flush()

function jzmqConnection::flush

(

in

me

)

Receives a command and associated data, optionally sending an 'ok' reply.

Calls receiveObject to get the command string and any serialized data. If sendReply is true (default) and a command was successfully received, it sends back an 'ok' command using sendObject.

Parameters

sendReply

(Optional) Logical flag. If true (default), sends an 'ok' reply upon successful receipt of a command. If false, no reply is sent by this function. Defaults to true.

Returns

command The received command string. Empty if receive failed or timed out.

data The deserialized MATLAB data received with the command. Empty if no data part or on error.

get()

function jzmqConnection::get	(	in	me,
		in	option
	)

Flushes the receive buffer of the socket.

Temporarily sets the receive timeout (ReceiveTimeOut) to 0 (non-blocking) and enters a loop calling receive until it returns a status of -1 (indicating no more messages or an error). It then restores the original readTimeOut. This is useful for discarding any pending messages in the socket's incoming queue.

open()

function jzmqConnection::open	(	in	me,
		in	context
	)

Class constructor for jzmqConnection.

Initializes a jzmqConnection object, setting up default properties and parsing any provided arguments using the optickaCore superclass constructor and argument parsing.

Parameters

varargin

Optional name-value pairs to override default properties. Allowed properties are defined in me.allowedProperties.

Returns

me An instance of the zmqConnection class.

poll()

function jzmqConnection::poll	(	in	me,
		in	events,
		in	time
	)

Opens the ØMQ socket connection.

Creates the ØMQ context if it doesn't exist, creates the socket based on the type property, sets socket options like ReceiveTimeOut, SNDTIMEO, and LINGER, and then either binds (for server types like REP, PUB, PUSH) or connects (for client types) to the specified endpoint. Sets the isOpen flag to true.

Note

Does nothing if the connection isOpen is already true.

receive()

function jzmqConnection::receive

(

in

me

)

Sends raw data over the socket.

Determines the type of data and calls the appropriate zmq.Socket send method (send_string for char/string, send for uint8). If the data type is different, it attempts to use the private sendObject method (which might not be intended for raw data).

Parameters

data	The data to send. Can be a character array, string, or uint8 array.

Returns

status 0 on success, -1 on failure (e.g., timeout, incorrect socket state).

receiveCommand()

function jzmqConnection::receiveCommand	(	in	me,
		in	sendReply
	)

Sends a command and optional data, then waits for a reply.

Primarily for REQ/REP patterns. Uses sendObject to send the command string and serialized data. If successful, it then calls receiveObject to wait for and receive the reply command and data.

Parameters

command	The command string to send.
data	(Optional) MATLAB data to serialize and send along with the command. Defaults to empty.

Returns

rep The reply command string received from the peer.

dataOut The deserialized MATLAB data received in the reply.

status 0 on success (send and receive completed), -1 on failure (send or receive failed).

receiveObject()

function jzmqConnection::receiveObject	(	in	me,
		in	useJSON,
		in	options
	)

(Private) Sends a command string and optional serialized MATLAB data.

This is the core sending method used by public methods like sendCommand and receiveCommand (for replies). It checks if the socket is open, validates the command is a string, serializes the data using getByteStreamFromArray (if provided), and sends the command and data as a two-part message using zmq.Socket.send with the 'sndmore' flag if both parts exist. Handles sending only command, only data, or an empty message if both are empty.

Parameters

command	The command string to send. Must be char or string.
data	(Optional) MATLAB data to serialize and send.
useJSON	(optional) wrap command and data with JSON

Returns

status 0 on success, -1 on failure.

nbytes The total number of bytes sent across all parts.

msg An error message string if status is -1.

send()

function jzmqConnection::send	(	in	me,
		in	data
	)

Sets the value of a ØMQ socket option.

A wrapper around the zmq.Socket.set method.

Parameters

option	The name of the socket option to set (e.g., 'ReceiveTimeOut', 'LINGER'). Case-insensitive, 'ZMQ_' prefix is optional.
value	The value to assign to the socket option.

Returns

status 0 on success, non-zero on failure.

Warning

Issues warnings if option or value are not provided.

sendCommand()

function jzmqConnection::sendCommand	(	in	me,
		in	command,
		in	data,
		in	getReply
	)

sendObject()

function jzmqConnection::sendObject	(	in	me,
		in	command,
		in	data,
		in	useJSON
	)

Sets the socket type.

Validates the socket type against a list of allowed types and sets the type property. Throws an error if the type is invalid.

Parameters

value

The socket type to set (e.g., 'REQ', 'REP', 'PUB', 'SUB').

Note

Uses SocketType enum, defaults to 'REQ'.

sendViaProxy()

function jzmqConnection::sendViaProxy	(	in	me,
		in	command,
		in	data,
		in	proxy
	)

(Private) Receives a command string and optional serialized MATLAB data.

This is the core receiving method. It calls zmq.Socket.recv to get the first part (expected to be the command string). It checks the 'rcvmore' socket option to see if a second part (data) exists. If so, it calls zmq.Socket.recv_multipart to get the remaining part(s), concatenates them if necessary, and deserializes the result using getArrayFromByteStream.

Parameters

options

(Optional) Cell array of flags for the initial recv call (e.g., {'ZMQ_DONTWAIT'}).

Returns

command The received command string. Empty on failure or timeout.

data The deserialized MATLAB data. Empty if no data part, deserialization fails, or on error.

raw the original structure

msg An error message string if receiving the command failed or deserialization failed.

Note

This is a private method. Throws an error if the socket is not open. Logs deserialization errors.

set()

function jzmqConnection::set	(	in	me,
		in	option,
		in	value
	)

Gets the value of a ØMQ socket option.

A wrapper around the zmq.Socket.get method.

Parameters

option

The name of the socket option to retrieve (e.g., 'Linger', 'ReceiveTimeOut'). Case-insensitive, 'ZMQ_' prefix is optional.

Returns

value The current value of the specified socket option.

Warning

Issues a warning if option is not provided.

type()

function set jzmqConnection::type	(	in	me,
		in	value
	)

Gets the full endpoint string for the connection.

Constructs the endpoint string (e.g., 'tcp://localhost:5555') based on the transport, address, and port properties.

Returns

endpoint The formatted endpoint string.

Member Data Documentation

address

Property jzmqConnection::address

the address to open, use * for a server to bind to all interfaces

alwaysPoll

Property jzmqConnection::alwaysPoll

for sendCommand and receiveCommand use zmq.core.poll?

endpoint

Property jzmqConnection::endpoint

connection endpoint

frameSize

Property jzmqConnection::frameSize

default size of chunk to read/write for tcp

httpProxy

Property jzmqConnection::httpProxy

use a http proxy to send message

port

Property jzmqConnection::port

the port to open

readTimeOut

Property jzmqConnection::readTimeOut

default read timeout in ms, -1 is blocking

transport

Property jzmqConnection::transport

transport for the socket, tcp | ipc | inproc

type

Property jzmqConnection::type

ØMQ connection type, e.g. 'REQ', 'REP', 'PUB', 'SUB', etc.

jzmqConnection is a class to handle ØMQ connections for opticka class communication. We use JeroMQ wrapper jzmq, a pure Java implementation of ØMQ.

verbose

Property jzmqConnection::verbose

do we log to the command window?

writeTimeOut

Property jzmqConnection::writeTimeOut

default write timeout in ms, -1 is blocking

---

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

• communication/jzmqConnection.m