UsageEnvironment/include/UsageEnvironment.hh

Go to the documentation of this file.
00001 /**********
00002 This library is free software; you can redistribute it and/or modify it under
00003 the terms of the GNU Lesser General Public License as published by the
00004 Free Software Foundation; either version 2.1 of the License, or (at your
00005 option) any later version. (See <http://www.gnu.org/copyleft/lesser.html>.)
00006 
00007 This library is distributed in the hope that it will be useful, but WITHOUT
00008 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
00009 FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
00010 more details.
00011 
00012 You should have received a copy of the GNU Lesser General Public License
00013 along with this library; if not, write to the Free Software Foundation, Inc.,
00014 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
00015 **********/
00016 // Copyright (c) 1996-2008 Live Networks, Inc.  All rights reserved.
00017 // Usage Environment
00018 // C++ header
00019 
00020 #ifndef _USAGE_ENVIRONMENT_HH
00021 #define _USAGE_ENVIRONMENT_HH
00022 
00023 #ifndef _USAGEENVIRONMENT_VERSION_HH
00024 #include "UsageEnvironment_version.hh"
00025 #endif
00026 
00027 #ifndef _NETCOMMON_H
00028 #include "NetCommon.h"
00029 #endif
00030 
00031 #ifndef _STRDUP_HH
00032 // "strDup()" is used often, so include this here, so everyone gets it:
00033 #include "strDup.hh"
00034 #endif
00035 
00036 #ifndef NULL
00037 #define NULL 0
00038 #endif
00039 
00040 #ifdef __BORLANDC__
00041 #define _setmode setmode
00042 #define _O_BINARY O_BINARY
00043 #endif
00044 
00045 class TaskScheduler; // forward
00046 
00047 // An abstract base class, subclassed for each use of the library
00048 
00049 class UsageEnvironment {
00050 public:
00051   void reclaim();
00052 
00053   // task scheduler:
00054   TaskScheduler& taskScheduler() const {return fScheduler;}
00055 
00056   // result message handling:
00057   typedef char const* MsgString;
00058   virtual MsgString getResultMsg() const = 0;
00059 
00060   virtual void setResultMsg(MsgString msg) = 0;
00061   virtual void setResultMsg(MsgString msg1, MsgString msg2) = 0;
00062   virtual void setResultMsg(MsgString msg1, MsgString msg2, MsgString msg3) = 0;
00063   virtual void setResultErrMsg(MsgString msg) = 0;
00064         // like setResultMsg(), except that an 'errno' message is appended
00065 
00066   virtual void appendToResultMsg(MsgString msg) = 0;
00067 
00068   virtual void reportBackgroundError() = 0;
00069         // used to report a (previously set) error message within
00070         // a background event
00071 
00072   // 'errno'
00073   virtual int getErrno() const = 0;
00074 
00075   // 'console' output:
00076   virtual UsageEnvironment& operator<<(char const* str) = 0;
00077   virtual UsageEnvironment& operator<<(int i) = 0;
00078   virtual UsageEnvironment& operator<<(unsigned u) = 0;
00079   virtual UsageEnvironment& operator<<(double d) = 0;
00080   virtual UsageEnvironment& operator<<(void* p) = 0;
00081 
00082   // a pointer to additional, optional, client-specific state
00083   void* liveMediaPriv;
00084   void* groupsockPriv;
00085 
00086 protected:
00087   UsageEnvironment(TaskScheduler& scheduler); // abstract base class
00088   virtual ~UsageEnvironment(); // we are deleted only by reclaim()
00089 
00090 private:
00091   TaskScheduler& fScheduler;
00092 };
00093 
00094 
00095 typedef void TaskFunc(void* clientData);
00096 typedef void* TaskToken;
00097 
00098 class TaskScheduler {
00099 public:
00100   virtual ~TaskScheduler();
00101 
00102   virtual TaskToken scheduleDelayedTask(int64_t microseconds, TaskFunc* proc,
00103                                         void* clientData) = 0;
00104         // Schedules a task to occur (after a delay) when we next
00105         // reach a scheduling point.
00106         // (Does not delay if "microseconds" <= 0)
00107         // Returns a token that can be used in a subsequent call to
00108         // unscheduleDelayedTask()
00109 
00110   virtual void unscheduleDelayedTask(TaskToken& prevTask) = 0;
00111         // (Has no effect if "prevTask" == NULL)
00112         // Sets "prevTask" to NULL afterwards.
00113 
00114   virtual void rescheduleDelayedTask(TaskToken& task,
00115                                      int64_t microseconds, TaskFunc* proc,
00116                                      void* clientData);
00117   // Combines "unscheduleDelayedTask()" with "scheduleDelayedTask()"
00118   // (setting "task" to the new task token).
00119 
00120   // For handling socket reads in the background:
00121   typedef void BackgroundHandlerProc(void* clientData, int mask);
00122     // Possible bits to set in "mask".  (These are deliberately defined
00123     // the same as those in Tcl, to make a Tcl-based subclass easy.)
00124     #define SOCKET_READABLE    (1<<1)
00125     #define SOCKET_WRITABLE    (1<<2)
00126     #define SOCKET_EXCEPTION   (1<<3)
00127   virtual void turnOnBackgroundReadHandling(int socketNum,
00128                                 BackgroundHandlerProc* handlerProc,
00129                                 void* clientData) = 0;
00130   virtual void turnOffBackgroundReadHandling(int socketNum) = 0;
00131 
00132   virtual void doEventLoop(char* watchVariable = NULL) = 0;
00133         // Stops the current thread of control from proceeding,
00134         // but allows delayed tasks (and/or background I/O handling)
00135         // to proceed.
00136         // (If "watchVariable" is not NULL, then we return from this
00137         // routine when *watchVariable != 0)
00138 
00139 protected:
00140   TaskScheduler(); // abstract base class
00141 };
00142 
00143 #endif

Generated on Tue Jul 22 06:39:07 2008 for live by  doxygen 1.5.2