0001 TPSETUNSOL(3)
0002 =============
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpsetunsol - Set unsolicited message callback handler function
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 void (*tpsetunsol (void (*'disp') (char *'data', long 'len', long 'flags'))) (char *'data', long 'len', long 'flags');
0016
0017
0018 For XATMI client link with '-latmiclt -latmi -lubf -lnstd -lpthread -lrt -lm'
0019
0020 For XATMI server link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd -lpthread -lrt -lm'
0021
0022 DESCRIPTION
0023 -----------
0024 Functions sets unsolicited message handler. On the return function returns previous handler.
0025 When system is initialized, the handler is set to *NULL* thus no callback function is
0026 registered for receiving unsolicited messages. When unsolicited message handling
0027 is needed, then 'disp' argument must be set to non NULL function. The signature for
0028 the function is:
0029
0030 --------------------------------------------------------------------------------
0031
0032 void notification_callback (char *data, long len, long flags);
0033
0034 --------------------------------------------------------------------------------
0035
0036 The notifications are received by this function, when somebody sends *tpnotify(3)*
0037 or *tpbroadcast(3)* to this client, and the *tpsetunsol()* handler is set. In that
0038 case the notification_callback callback function is invoked with XATMI allocated
0039 buffer in variable 'data' and 'len'. The user shall not free the buffer,
0040 as it is automatically freed when function finishes processing. The 'flags' parameter
0041 currently is not used.
0042
0043 Callbacks are processed in case if in progress *tpcall(3)* or *tpgetrply(3)*
0044 receives the notification. In that case callback is invoked.
0045 The other option to process notification is that user process manually calls
0046 *tpchkunsol(3)* at some time interval.
0047
0048 The processing that can be done inside the callback is limited to following functions:
0049
0050 . tpalloc()
0051
0052 . tpfree()
0053
0054 . tpgetlev()
0055
0056 . tprealloc()
0057
0058 . tptypes()
0059
0060 So basically if some significant processing is required within the callback, the
0061 user shall allocate new XATMI buffer, copy the data to it and create new thread.
0062 The copied data shall be passed to the thread for processing. And in the end
0063 callback can do return.
0064
0065 Enduro/X does not strictly control what API is used within the callback. It is up
0066 to user to follow these rules, otherwise unexpected behavior might occur.
0067
0068 Callback handler is stored in thread local storage.
0069
0070 RETURN VALUE
0071 ------------
0072 On success, *tpsetunsol()* return previous function pointer, might be NULL too;
0073 on error, TPUNSOLERR is returned, with *tperrno* set to indicate the error.
0074
0075
0076 ERRORS
0077 ------
0078 Note that *tpstrerror()* returns generic error message plus custom message with
0079 debug info from last function call.
0080
0081 *TPEINVAL* Environment variables not configured, see *ex_env(5)* page.
0082
0083 *TPESYSTEM* System failure occurred during serving. See logs i.e. user log,
0084 or debugs for more info.
0085
0086 *TPEOS* System failure occurred during serving. See logs i.e. user log,
0087 or debugs for more info.
0088
0089
0090 EXAMPLE
0091 -------
0092 See *atmitest/test038_tpnotify/atmiclt38.c* for sample code.
0093
0094 BUGS
0095 ----
0096 Report bugs to support@mavimax.com
0097
0098 SEE ALSO
0099 --------
0100 *tpnotify(3)* *tpbroadcast(3)* *tpchkunsol(3)* *tpinit(3)*
0101
0102 COPYING
0103 -------
0104 (C) Mavimax, Ltd
0105
