0001 TPSUBSCRIBE(3)
0002 ==============
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpsubscribe - Subscribe to event
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 long tpsubscribe (char *'eventexpr', char *'filter', TPEVCTL *'ctl', long 'flags');
0016
0017
0018 Link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd -lpthread -lrt -lm'
0019
0020 DESCRIPTION
0021 -----------
0022 Subscribe to event. This is API function for Enduro/X event broker services.
0023 In order to get the functionality working, then event server must be started and
0024 configured. See *tpevsrv(8)* manpage. 'eventexpr' is regular expression
0025 syntax based expression which is registered into event broker, so that if it
0026 is matched then event is posted to service, written in 'ctl->name1' field.
0027 Note that many servers with the same service can subscribe to same event.
0028 All server's services will receive the event. 'filter' is boolean expression
0029 for *UBF* or regular expression for *STRING* buffer which are extra expression
0030 to be tested on the event data buffer prior event deliver. If 'filter' is true or *NULL*,
0031 then event is posted to service.
0032
0033 The *TPEVCTL* structure is following:
0034
0035 --------------------------------------------------------------------------------
0036
0037 struct tpevctl_t
0038 {
0039 long flags;
0040 char name1[XATMI_SERVICE_NAME_LENGTH+1];
0041 char name2[XATMI_SERVICE_NAME_LENGTH+1];
0042 };
0043 typedef struct tpevctl_t TPEVCTL;
0044
0045 --------------------------------------------------------------------------------
0046
0047 'ctl->name2' is reserved for future use.
0048
0049 *NOTE:* that if multiple server binaries are advertising some service
0050 lets say "MYSVC" and event is subscribed for any of the server binaries, then
0051 if event is triggered, it will be delivered to "MYSVC" service as a one message.
0052 There is guarantee to which copy message will pass. Thus if all servers needs to
0053 be notified with the event, each server shall advertise unique server name and
0054 subscribe it to particular event. In that case matching event will be delivered
0055 to all interested executables. For example:
0056
0057 --------------------------------------------------------------------------------
0058
0059 int tpsvrinit(int argc, char **argv)
0060 {
0061 TPEVCTL evctl;
0062 char svcnm[XATMI_SERVICE_NAME_LENGTH+1];
0063
0064 snprintf(svcnm, sizeof(svcnm), "MYSVC_%d", tpgetsrvid())
0065
0066 if (EXSUCCEED!=tpadvertise(svcnm, MYSVC))
0067 {
0068 NDRX_LOG(log_error, "Failed to advertise %s!", svcnm);
0069 ret=EXFAIL;
0070 goto out;
0071 }
0072
0073 memset(&evctl, 0, sizeof(evctl));
0074
0075 NDRX_STRCPY_SAFE(evctl.name1, svcnm);
0076 evctl.flags|=TPEVSERVICE;
0077
0078 /* Subscribe to event server */
0079 if (EXFAIL==tpsubscribe("EVTEST", NULL, &evctl, 0L))
0080 {
0081 NDRX_LOG(log_error, "Failed to subscribe to EVTEST: %s",
0082 tpstrerror(tperrno));
0083 ret=EXFAIL;
0084 goto out;
0085 }
0086
0087 out:
0088 return ret;
0089 }
0090 --------------------------------------------------------------------------------
0091
0092
0093
0094 *Valid flags*
0095
0096 *TPSIGRSTRT* Restart the system call in progress if interrupted by signal
0097 handler. This affects only underlying mq_* function calls.
0098
0099 *TPNOTIME* Ignore timeout setting (*NDRX_TOUT* env variable).
0100 Wait for reply for infinitely.
0101
0102 *Valid ctl->flags*
0103
0104 *TPEVSERVICE* Call the service. Note that service will be called with
0105 flags which are present at 'ctl->flags' | *TPNOREPLY*.
0106
0107 *TPEVPERSIST* Do not remove service for event brokers registry, if service
0108 is not available any more (detected at point *tpcall()* to service failed).
0109
0110 This function is available only for XATMI servers.
0111
0112 RETURN VALUE
0113 ------------
0114 On success, *tpsubscribe()* return subscription id; on error, -1 is
0115 returned, with *tperrno* set to indicate the error.
0116
0117 ERRORS
0118 ------
0119 Note that *tpstrerror()* returns generic error message plus custom message
0120 with debug info from last function call.
0121
0122 *TPEINVAL* Invalid parameter is given to function. Event expression is *NULL*
0123 or empty. Event expression is longer than 255 bytes, 'ctl' is NULL,
0124 or 'clt->name1' is empty or filter is set and longer than 255 bytes.
0125
0126 *TPENOENT* Event server is not available.
0127
0128 *TPETIME* Service did not reply in given time ('NDRX_TOUT').
0129
0130 *TPESVCFAIL* Service returned 'TPFAIL'. This is application level failure.
0131
0132 *TPESVCERR* System level service failure. Server died during the message
0133 presence in service queue.
0134
0135 *TPESYSTEM* System failure occurred during serving. See logs i.e. user log,
0136 or debugs for more info.
0137
0138 *TPEOS* System failure occurred during serving. See logs i.e. user log,
0139 or debugs for more info.
0140
0141 BUGS
0142 ----
0143 Report bugs to support@mavimax.com
0144
0145 EXAMPLE
0146 -------
0147 See *atmitest/test004_basicevent/atmisv4_1ST.c* for sample code.
0148
0149 SEE ALSO
0150 --------
0151 *tpevsrv(8)* *tpunsubscribe(3)* *tppost(3)*
0152
0153 COPYING
0154 -------
0155 (C) Mavimax, Ltd
0156
