1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
.TH "psmq_publish" "3" "19 May 2021 (v9999)" "bofc.pl"
.SH NAME
.PP
.B psmq_publish
- publish message over
.BR psmq.
.SH SYNOPSIS
.PP
.BI "#include <psmq.h>"
.PP
.BI "int psmq_publish(struct psmq *" psmq ", const char *" topic ", \
const void *" payload ", size_t " paylen ", unsigned int " prio ")"
.SH DESCRIPTION
.PP
Publishes message with
.I payload
data of size
.I paylen
on
.I topic
with specified
.I prio
to broker connected in
.IR psmq .
It's ok to set
.I payload
to
.BR NULL .
In that case
.I paylen
will be automatically set to 0.
.PP
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 broker never blocks waiting for clients, so messages from mqueue are
processed immediately and without unnecessary delays.
.PP
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
.I topic
or client's queue is full and broker dropped that message instead.
.PP
When publishing you need to publish to very specific topic (like
"/can/engine/rpm") - you cannot use
wildcards in
.I topic
(like "/can/engine/+").
.PP
When sending message, both
.I topic
and
.I payload
share single buffer of size
.BR 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
(as in PSMQ_MSG_MAX - 1 large) and no payload, and next publish can
be opposite - short topic but large payload.
.SH "RETURN VALUE"
.PP
0 on success. -1 on errors with appropriate errno set.
.SH ERRORS
.TP
.B EINVAL
.I psmq
or
.I topic
is
.B NULL
.TP
.B EBADF
.I psmq
has not yet been initialized
.TP
.B ENOBUFS
.I topic
and/or
.I payload
are too big to fit into message buffer.
.TP
.B EBADMSG
.I topic
does not start with \'/\' character.
.SH EXAMPLE
Send message over
.B psmq
with information about revolution per minute of engine.
Error checking ommited for better readability.
.PP
.nf
#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;
}
.nf
.SH "BUG REPORTING"
.PP
Please, report all bugs to "Michał Łyszczek <michal.lyszczek@bofc.pl>"
.SH "SEE ALSO"
.PP
.BR psmqd (1),
.BR psmq-pub (1),
.BR psmq-sub (1),
.BR psmq_cleanup (3),
.BR psmq_init (3),
.BR psmq_publish (3),
.BR psmq_receive (3),
.BR psmq_subscribe (3),
.BR psmq_timedreceive (3),
.BR psmq_timedreceive_ms (3),
.BR psmq_unsubscribe (3),
.BR psmq_building (7),
.BR psmq_overview (7).
|
