psmq_publish(3)

bofc manual pages

psmq_publish(3)



 

NAME

psmq_publish - publish message over psmq.  

SYNOPSIS

#include <psmq.h>

int psmq_publish(struct psmq *psmq, const char *topic, const void *payload, size_t paylen, unsigned int prio)  

DESCRIPTION

Publishes message with payload data of size paylen on topic with specified prio to broker connected in psmq. It's ok to set payload to NULL. In that case paylen will be automatically set to 0.

If broker's control mqueue is full then this function will block until broker deals with some messages and make place in the queue. Note that, by default, broker never blocks waiting for clients, so messages from mqueue are processed immediately and without unnecessary delays. Broker may block waiting for clients when you set high enough response timeout value via psmq_ioctl_reply_timeout(3).

Successfull call means that message has been put into broker's queue with success it doesn't necessary mean that any client will receives that message. It is possible that no clients currently listens on sent topic or client's queue is full and broker dropped that message instead.

When publishing you need to publish to very specific topic (like "/can/engine/rpm") - you cannot use wildcards in topic (like "/can/engine/+").

When sending message, both topic and payload share single buffer of size PSMQ_MSG_MAX. This means topic size + payload size cannot exceed that value. Note, that topic will take strlen(topic) + 1 size on buffer, since topic is string so it will also transmit null terminator char. This allows for some flexibility, as one message can contain large topic (as in PSMQ_MSG_MAX - 1 large) and no payload, and next publish can be opposite - short topic but large payload.

Only real data is sent over mqueue, if PSMQ_MSG_MAX is large like 256 bytes, but topic + payload is 10 bytes long, only these 10 bytes will be actually copied over to the broker and clients, not full buffer (256 bytes).  

RETURN VALUE

0 on success. -1 on errors with appropriate errno set.  

ERRORS

EINVAL
psmq or topic is NULL
EBADF
psmq has not yet been initialized
ENOBUFS
topic and/or payload are too big to fit into message buffer.
EBADMSG
topic does not start with '/' character.
 

EXAMPLE

Send message over psmq with information about revolution per minute of engine. Error checking ommited for better readability.
    #include <psmq.h>

    int main(void)
    {
        struct psmq psmq;
        int rpm;

        /* initialize psmq object that will create /sub mqueue for
         * receiving data, and will connect to broker of name /brok.
         * Max items in queue is set to 10 */
        psmq_init(&psmq, "/brok", "/sub", 10);

        /* if we don't want to receive any message, we can skip
         * susbscribe function. */
        /* Now simply send message to broker */
        rpm = 1;
        psmq_publish(&psmq, "/can/engine/rpm", &rpm, sizeof(rpm), 0);

        /* after work is finished, we need to deregister from broker to
         * make space in broker for another client */
        psmq_cleanup(&psmq);
        return 0;
    }
 

BUG REPORTING

Please, report all bugs to "Michał Łyszczek <michal.lyszczek@bofc.pl>"  

SEE ALSO

psmqd(1), psmq-pub(1), psmq-sub(1), psmq_cleanup(3), psmq_init(3), psmq_publish(3), psmq_receive(3), psmq_subscribe(3), psmq_timedreceive(3), psmq_timedreceive_ms(3), psmq_unsubscribe(3), psmq_building(7), psmq_overview(7).

bofc.pl

19 May 2021 (v9999)

psmq_publish(3)