1/**********
2This library is free software; you can redistribute it and/or modify it under
3the terms of the GNU Lesser General Public License as published by the
4Free Software Foundation; either version 3 of the License, or (at your
5option) any later version. (See <http://www.gnu.org/copyleft/lesser.html>.)
6
7This library is distributed in the hope that it will be useful, but WITHOUT
8ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
9FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
10more details.
11
12You should have received a copy of the GNU Lesser General Public License
13along with this library; if not, write to the Free Software Foundation, Inc.,
1451 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
15**********/
16// Copyright (c) 1996-2020 Live Networks, Inc. All rights reserved.
17// Usage Environment
18// C++ header
19
20#ifndef _USAGE_ENVIRONMENT_HH
21#define _USAGE_ENVIRONMENT_HH
22
23#ifndef _USAGEENVIRONMENT_VERSION_HH
24#include "UsageEnvironment_version.hh"
25#endif
26
27#ifndef _NETCOMMON_H
28#include "NetCommon.h"
29#endif
30
31#ifndef _BOOLEAN_HH
32#include "Boolean.hh"
33#endif
34
35#ifndef _STRDUP_HH
36// "strDup()" is used often, so include this here, so everyone gets it:
37#include "strDup.hh"
38#endif
39
40#ifndef NULL
41#define NULL 0
42#endif
43
44#ifdef __BORLANDC__
45#define _setmode setmode
46#define _O_BINARY O_BINARY
47#endif
48
49class TaskScheduler; // forward
50
51// An abstract base class, subclassed for each use of the library
52
53class UsageEnvironment {
54public:
55 Boolean reclaim();
56 // returns True iff we were actually able to delete our object
57
58 // task scheduler:
59 TaskScheduler& taskScheduler() const {return fScheduler;}
60
61 // result message handling:
62 typedef char const* MsgString;
63 virtual MsgString getResultMsg() const = 0;
64
65 virtual void setResultMsg(MsgString msg) = 0;
66 virtual void setResultMsg(MsgString msg1, MsgString msg2) = 0;
67 virtual void setResultMsg(MsgString msg1, MsgString msg2, MsgString msg3) = 0;
68 virtual void setResultErrMsg(MsgString msg, int err = 0) = 0;
69 // like setResultMsg(), except that an 'errno' message is appended. (If "err == 0", the "getErrno()" code is used instead.)
70
71 virtual void appendToResultMsg(MsgString msg) = 0;
72
73 virtual void reportBackgroundError() = 0;
74 // used to report a (previously set) error message within
75 // a background event
76
77 virtual void internalError(); // used to 'handle' a 'should not occur'-type error condition within the library.
78
79 // 'errno'
80 virtual int getErrno() const = 0;
81
82 // 'console' output:
83 virtual UsageEnvironment& operator<<(char const* str) = 0;
84 virtual UsageEnvironment& operator<<(int i) = 0;
85 virtual UsageEnvironment& operator<<(unsigned u) = 0;
86 virtual UsageEnvironment& operator<<(double d) = 0;
87 virtual UsageEnvironment& operator<<(void* p) = 0;
88
89 // a pointer to additional, optional, client-specific state
90 void* liveMediaPriv;
91 void* groupsockPriv;
92
93protected:
94 UsageEnvironment(TaskScheduler& scheduler); // abstract base class
95 virtual ~UsageEnvironment(); // we are deleted only by reclaim()
96
97private:
98 TaskScheduler& fScheduler;
99};
100
101
102typedef void TaskFunc(void* clientData);
103typedef void* TaskToken;
104typedef u_int32_t EventTriggerId;
105
106class TaskScheduler {
107public:
108 virtual ~TaskScheduler();
109
110 virtual TaskToken scheduleDelayedTask(int64_t microseconds, TaskFunc* proc,
111 void* clientData) = 0;
112 // Schedules a task to occur (after a delay) when we next
113 // reach a scheduling point.
114 // (Does not delay if "microseconds" <= 0)
115 // Returns a token that can be used in a subsequent call to
116 // unscheduleDelayedTask() or rescheduleDelayedTask()
117 // (but only if the task has not yet occurred).
118
119 virtual void unscheduleDelayedTask(TaskToken& prevTask) = 0;
120 // (Has no effect if "prevTask" == NULL)
121 // Sets "prevTask" to NULL afterwards.
122 // Note: This MUST NOT be called if the scheduled task has already occurred.
123
124 virtual void rescheduleDelayedTask(TaskToken& task,
125 int64_t microseconds, TaskFunc* proc,
126 void* clientData);
127 // Combines "unscheduleDelayedTask()" with "scheduleDelayedTask()"
128 // (setting "task" to the new task token).
129 // Note: This MUST NOT be called if the scheduled task has already occurred.
130
131 // For handling socket operations in the background (from the event loop):
132 typedef void BackgroundHandlerProc(void* clientData, int mask);
133 // Possible bits to set in "mask". (These are deliberately defined
134 // the same as those in Tcl, to make a Tcl-based subclass easy.)
135 #define SOCKET_READABLE (1<<1)
136 #define SOCKET_WRITABLE (1<<2)
137 #define SOCKET_EXCEPTION (1<<3)
138 virtual void setBackgroundHandling(int socketNum, int conditionSet, BackgroundHandlerProc* handlerProc, void* clientData) = 0;
139 void disableBackgroundHandling(int socketNum) { setBackgroundHandling(socketNum, 0, NULL, NULL); }
140 virtual void moveSocketHandling(int oldSocketNum, int newSocketNum) = 0;
141 // Changes any socket handling for "oldSocketNum" so that occurs with "newSocketNum" instead.
142
143 virtual void doEventLoop(char volatile* watchVariable = NULL) = 0;
144 // Causes further execution to take place within the event loop.
145 // Delayed tasks, background I/O handling, and other events are handled, sequentially (as a single thread of control).
146 // (If "watchVariable" is not NULL, then we return from this routine when *watchVariable != 0)
147
148 virtual EventTriggerId createEventTrigger(TaskFunc* eventHandlerProc) = 0;
149 // Creates a 'trigger' for an event, which - if it occurs - will be handled (from the event loop) using "eventHandlerProc".
150 // (Returns 0 iff no such trigger can be created (e.g., because of implementation limits on the number of triggers).)
151 virtual void deleteEventTrigger(EventTriggerId eventTriggerId) = 0;
152
153 virtual void triggerEvent(EventTriggerId eventTriggerId, void* clientData = NULL) = 0;
154 // Causes the (previously-registered) handler function for the specified event to be handled (from the event loop).
155 // The handler function is called with "clientData" as parameter.
156 // Note: This function (unlike other library functions) may be called from an external thread
157 // - to signal an external event. (However, "triggerEvent()" should not be called with the
158 // same 'event trigger id' from different threads.)
159
160 // The following two functions are deprecated, and are provided for backwards-compatibility only:
161 void turnOnBackgroundReadHandling(int socketNum, BackgroundHandlerProc* handlerProc, void* clientData) {
162 setBackgroundHandling(socketNum, SOCKET_READABLE, handlerProc, clientData);
163 }
164 void turnOffBackgroundReadHandling(int socketNum) { disableBackgroundHandling(socketNum); }
165
166 virtual void internalError(); // used to 'handle' a 'should not occur'-type error condition within the library.
167
168protected:
169 TaskScheduler(); // abstract base class
170};
171
172#endif
173