| // Copyright (C) 2006-2010 David Sugar, Tycho Softworks. |
| // |
| // This file is part of GNU uCommon C++. |
| // |
| // GNU uCommon C++ is free software: you can redistribute it and/or modify |
| // it under the terms of the GNU Lesser General Public License as published |
| // by the Free Software Foundation, either version 3 of the License, or |
| // (at your option) any later version. |
| // |
| // GNU uCommon C++ is distributed in the hope that it will be useful, |
| // but WITHOUT ANY WARRANTY; without even the implied warranty of |
| // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| // GNU Lesser General Public License for more details. |
| // |
| // You should have received a copy of the GNU Lesser General Public License |
| // along with GNU uCommon C++. If not, see <http://www.gnu.org/licenses/>. |
| |
| /** |
| * Abstract interfaces and support. This is a set of "protocols", a concept |
| * borrowed from other object oriented languages, to define interfaces for |
| * low level services. By using a protocol base class which offers both |
| * virtuals and support methods only, one can easily stack and share these |
| * as common base classes without having to consider when the final derived |
| * object implements them. Core protocol methods always are tagged with a |
| * _ prefix to make it easier to track their derivation. |
| * @file ucommon/protocols.h |
| * @author David Sugar <dyfet@gnutelephony.org> |
| */ |
| |
| #ifndef _UCOMMON_PROTOCOLS_H_ |
| #define _UCOMMON_PROTOCOLS_H_ |
| |
| #ifndef _UCOMMON_CPR_H_ |
| #include <ucommon/cpr.h> |
| #endif |
| |
| NAMESPACE_UCOMMON |
| |
| class String; |
| class StringPager; |
| |
| class __EXPORT MemoryProtocol |
| { |
| protected: |
| friend class MemoryRedirect; |
| |
| /** |
| * Protocol to allocate memory from the pager heap. The size of the |
| * request must be less than the size of the memory page used. The |
| * actual method is in a derived or stacked object. |
| * @param size of memory request. |
| * @return allocated memory or NULL if not possible. |
| */ |
| virtual void *_alloc(size_t size) = 0; |
| |
| /** |
| * Allocation failure handler. |
| */ |
| virtual void fault(void) const; |
| |
| public: |
| virtual ~MemoryProtocol(); |
| |
| /** |
| * Convenience function. |
| * @param size of memory request. |
| * @return alocated memory or NULL if not possible. |
| */ |
| inline void *alloc(size_t size) |
| {return _alloc(size);}; |
| |
| /** |
| * Allocate memory from the pager heap. The size of the request must be |
| * less than the size of the memory page used. The memory is initialized |
| * to zero. This uses alloc. |
| * @param size of memory request. |
| * @return allocated memory or NULL if not possible. |
| */ |
| void *zalloc(size_t size); |
| |
| /** |
| * Duplicate NULL terminated string into allocated memory. This uses |
| * alloc. |
| * @param string to copy into memory. |
| * @return allocated memory with copy of string or NULL if cannot allocate. |
| */ |
| char *dup(const char *string); |
| |
| /** |
| * Duplicate existing memory block into allocated memory. This uses alloc. |
| * @param memory to data copy from. |
| * @param size of memory to allocate. |
| * @return allocated memory with copy or NULL if cannot allocate. |
| */ |
| void *dup(void *memory, size_t size); |
| }; |
| |
| /** |
| * A redirection base class for the memory protocol. This is used because |
| * sometimes we choose a common memory pool to manage different objects. |
| * @author David Sugar <dyfet@gnutelephony.org> |
| */ |
| class __EXPORT MemoryRedirect : public MemoryProtocol |
| { |
| private: |
| MemoryProtocol *target; |
| |
| public: |
| MemoryRedirect(MemoryProtocol *protocol); |
| |
| virtual void *_alloc(size_t size); |
| }; |
| |
| /** |
| * Common locking protocol. This is used for objects that may internally |
| * have sync'd functions, directly or in a derived class, that lock the |
| * current object. The default handlers do nothing but offer the virtuals |
| * as a stub. |
| * @author David Sugar <dyfet@gnutelephony.org> |
| */ |
| class __EXPORT LockingProtocol |
| { |
| protected: |
| virtual void _lock(void); |
| virtual void _unlock(void); |
| |
| public: |
| virtual ~LockingProtocol(); |
| }; |
| |
| /** |
| * Used for forming stream output. We would create a derived class who's |
| * constructor creates an internal string object, and a single method to |
| * extract that string. |
| * @author David Sugar <dyfet@gnutelephony.org> |
| */ |
| class __EXPORT PrintProtocol |
| { |
| public: |
| virtual ~PrintProtocol(); |
| |
| /** |
| * Extract formatted string for object. |
| */ |
| virtual const char *_print(void) const = 0; |
| }; |
| |
| /** |
| * Used for processing input. We create a derived class that processes a |
| * single character of input, and returns a status value. EOF means it |
| * accepts no more input and any value other than 0 is a character to also |
| * unget. Otherwise 0 is good to accept more input. The constructor is |
| * used to reference a final destination object in the derived class. |
| * @author David Sugar <dyfet@gnutelephony.org> |
| */ |
| class __EXPORT InputProtocol |
| { |
| public: |
| virtual ~InputProtocol(); |
| |
| /** |
| * Extract formatted string for object. |
| * @param character code we are pushing. |
| * @return 0 to keep processing, EOF if done, or char to unget. |
| */ |
| virtual int _input(int code) = 0; |
| }; |
| |
| /** |
| * Common character processing protocol. This is used to access a character |
| * from some type of streaming buffer or memory object. |
| * @author David Sugar <dyfet@gnutelephony.org> |
| */ |
| class __EXPORT CharacterProtocol |
| { |
| protected: |
| const char *eol; |
| int back; |
| |
| CharacterProtocol(); |
| |
| /** |
| * Get the next character. |
| * @return next character or EOF. |
| */ |
| virtual int _getch(void) = 0; |
| |
| /** |
| * Put the next character. |
| * @param code to put. |
| * @return code or EOF if cannot put. |
| */ |
| virtual int _putch(int code) = 0; |
| |
| /** |
| * Write to back buffer. Mostly used for input format processing. |
| * @param code to write into backbuffer. |
| */ |
| inline void putback(int code) |
| {back = code;} |
| |
| /** |
| * Set end of line marker. Normally this is set to cr & lf, which |
| * actually supports both lf alone and cr/lf termination of lines. |
| * However, putline() will always add the full cr/lf if this mode is |
| * used. This option only effects getline() and putline(). |
| * @param string for eol for getline and putline. |
| */ |
| inline void seteol(const char *string) |
| {eol = string;}; |
| |
| public: |
| virtual ~CharacterProtocol(); |
| |
| /** |
| * Get the next character. |
| * @return next character or EOF. |
| */ |
| inline int getchar(void) |
| {return _getch();}; |
| |
| /** |
| * Put the next character. |
| * @param code to put. |
| * @return code or EOF if cannot put. |
| */ |
| inline int putchar(int code) |
| {return _putch(code);}; |
| |
| size_t print(const PrintProtocol& format); |
| |
| size_t input(InputProtocol& format); |
| |
| /** |
| * Get text as a line of input from the buffer. The eol character(s) |
| * are used to mark the end of a line. Because the end of line character |
| * is stripped, the length of the string may be less than the actual |
| * count read. If at the end of the file buffer and unable to read more |
| * data an error occured then 0 is returned. |
| * @param string to save input into. |
| * @param size limit of string to save. |
| * @return count of characters actually read or 0 if at end of data. |
| */ |
| size_t getline(char *string, size_t size); |
| |
| /** |
| * Get a string as a line of input from the buffer. The eol character(s) |
| * are used to mark the end of a line. Because the end of line character |
| * is stripped, the length of the string may be less than the actual |
| * count read. If at the end of the file buffer and unable to read more |
| * data an error occured then 0 is returned. |
| * @param buffer to save input into. |
| * @return count of characters actually read or 0 if at end of data. |
| */ |
| size_t getline(String& buffer); |
| |
| /** |
| * Put a string as a line of output to the buffer. The eol character is |
| * appended to the end. |
| * @param string to write. |
| * @return total characters successfully written, including eol chars. |
| */ |
| size_t putline(const char *string); |
| |
| size_t putchars(const char *string, size_t count = 0); |
| |
| /** |
| * Load input to a string list. The string list filter method is used to |
| * control loading. |
| * @param list to load into. |
| * @return number of items loaded. |
| */ |
| size_t load(StringPager *list); |
| |
| /** |
| * Save output from a string list. |
| * @param list to save from. |
| * @return number of items loaded. |
| */ |
| size_t save(const StringPager *list); |
| }; |
| |
| /** |
| * Common buffer protocol class. This is used to create objects which will |
| * stream character data as needed. This class can support bidirectional |
| * streaming as may be needed for serial devices, sockets, and pipes. The |
| * buffering mechanisms are hidden from derived classes, and two virtuals |
| * are used to communicate with the physical transport. |
| * @author David Sugar <dyfet@gnutelephony.org> |
| */ |
| class __EXPORT BufferProtocol : public CharacterProtocol |
| { |
| public: |
| typedef enum {RDONLY, WRONLY, RDWR} mode_t; |
| |
| private: |
| char *buffer; |
| char *input, *output; |
| size_t bufsize, bufpos, insize, outsize; |
| bool end; |
| |
| protected: |
| const char *format; |
| |
| /** |
| * Construct an empty (unallocated) buffer. |
| */ |
| BufferProtocol(); |
| |
| /** |
| * Construct a buffer of pre-allocated size and access type. |
| * @param size of buffer to allocate. |
| * @param access mode of buffer. |
| */ |
| BufferProtocol(size_t size, mode_t access = RDWR); |
| |
| /** |
| * Destroy object by releasing buffer memory. |
| */ |
| virtual ~BufferProtocol(); |
| |
| /** |
| * Allocation error handler. |
| */ |
| virtual void fault(void) const; |
| |
| /** |
| * Allocate I/O buffer(s) of specified size. If a buffer is currently |
| * allocated, it is released. |
| * @param size of buffer to allocate. |
| * @param access mode of buffer. |
| */ |
| void allocate(size_t size, mode_t access = RDWR); |
| |
| /** |
| * Release (free) buffer memory. |
| */ |
| void release(void); |
| |
| /** |
| * Request workspace in output buffer. This returns a pointer to |
| * memory from the output buffer and advances the output position. |
| * This is sometimes used for a form of zero copy write. |
| * @param size of request area. |
| * @return data pointer or NULL if not available. |
| */ |
| char *request(size_t size); |
| |
| /** |
| * Gather returns a pointer to contiguous input of specified size. |
| * This may require moving the input data in memory. |
| * @param size of gather space. |
| * @return data pointer to gathered data or NULL if not available. |
| */ |
| char *gather(size_t size); |
| |
| /** |
| * Method to push buffer into physical i/o (write). The address is |
| * passed to this virtual since it is hidden as private. |
| * @param address of data to push. |
| * @param size of data to push. |
| * @return number of bytes written, 0 on error. |
| */ |
| virtual size_t _push(const char *address, size_t size) = 0; |
| |
| /** |
| * Method to pull buffer from physical i/o (read). The address is |
| * passed to this virtual since it is hidden as private. |
| * @param address of buffer to pull data into. |
| * @param size of buffer area being pulled.. |
| * @return number of read written, 0 on error or end of data. |
| */ |
| virtual size_t _pull(char *address, size_t size) = 0; |
| |
| /** |
| * Method to get low level i/o error. |
| * @return error from low level i/o methods. |
| */ |
| virtual int _err(void) const = 0; |
| |
| /** |
| * Method to clear low level i/o error. |
| */ |
| virtual void _clear(void) = 0; |
| |
| /** |
| * Return true if blocking. |
| */ |
| virtual bool _blocking(void); |
| |
| /** |
| * Check if data is pending. |
| */ |
| virtual bool _pending(void); |
| |
| /** |
| * Flush buffer to physical i/o. |
| */ |
| virtual bool _flush(void); |
| |
| virtual int _getch(void); |
| |
| virtual int _putch(int ch); |
| |
| /** |
| * Get current input position. Sometimes used to help compute and report |
| * a "tell" offset. |
| * @return offset of input buffer. |
| */ |
| inline size_t input_pending(void) |
| {return bufpos;}; |
| |
| /** |
| * Get current output position. Sometimes used to help compute a |
| * "trunc" operation. |
| */ |
| inline size_t output_waiting(void) |
| {return outsize;}; |
| |
| public: |
| const char *endl(void) |
| {return eol;} |
| |
| /** |
| * Put memory into the buffer. If count is 0 then put as NULL |
| * terminated string. |
| * @param address of characters to put into buffer. |
| * @param count of characters to put into buffer. |
| * @return number of characters actually written. |
| */ |
| size_t put(const void *address, size_t count); |
| |
| /** |
| * Get memory from the buffer. |
| * @param address of characters save from buffer. |
| * @param count of characters to get from buffer. |
| * @return number of characters actually copied. |
| */ |
| size_t get(void *address, size_t count); |
| |
| /** |
| * Print formatted string to the buffer. The maximum output size is |
| * the buffer size, and the operation flushes the buffer. |
| * @param format string. |
| * @return number of bytes written. |
| */ |
| size_t printf(const char *format, ...) __PRINTF(2, 3); |
| |
| /** |
| * Flush buffered memory to physical I/O. |
| * @return true on success, false if not active or fails. |
| */ |
| inline bool flush(void) |
| {return _flush();} |
| |
| /** |
| * Purge any pending input or output buffer data. |
| */ |
| void purge(void); |
| |
| /** |
| * Reset input buffer state. Drops any pending input. |
| */ |
| void reset(void); |
| |
| /** |
| * Check if at end of input. |
| * @return true if end of data, false if input still buffered. |
| */ |
| bool eof(void); |
| |
| /** |
| * See if buffer open. |
| * @return true if buffer active. |
| */ |
| inline operator bool() |
| {return buffer != NULL;} |
| |
| /** |
| * See if buffer closed. |
| * @return true if buffer inactive. |
| */ |
| inline bool operator!() |
| {return buffer == NULL;} |
| |
| /** |
| * See if buffer open. |
| * @return true if buffer active. |
| */ |
| inline bool is_open(void) |
| {return buffer != NULL;} |
| |
| /** |
| * See if input active. |
| * @return true if input active. |
| */ |
| inline bool is_input(void) |
| {return input != NULL;} |
| |
| /** |
| * See if output active. |
| * @return true if output active. |
| */ |
| inline bool is_output(void) |
| {return output != NULL;} |
| |
| /** |
| * See if pending input. |
| * @return true if input pending. |
| */ |
| inline bool is_pending(void) |
| {return _pending();} |
| |
| /** |
| * Set eof flag. |
| */ |
| inline void seteof(void) |
| {end = true;} |
| |
| inline int err(void) |
| {return _err();} |
| |
| template<typename T> inline size_t write(const T& data) |
| {return put(&data, sizeof(T));} |
| |
| template<typename T> inline size_t read(T& data) |
| {return get(&data, sizeof(T));} |
| |
| template<typename T> inline size_t write(const T* data, unsigned count) |
| {return put(data, sizeof(T) * count) / sizeof(T);} |
| |
| template<typename T> inline size_t read(T* data, unsigned count) |
| {return get(data, sizeof(T) * count) / sizeof(T);} |
| |
| }; |
| |
| /** |
| * A common base class for all managed objects. This is used to manage |
| * objects that might be linked or reference counted. The base class defines |
| * only core virtuals some common public methods that should be used by |
| * all inherited object types. |
| * @author David Sugar <dyfet@gnutelephony.org> |
| */ |
| class __EXPORT ObjectProtocol |
| { |
| public: |
| /** |
| * Method to retain (or increase retention) of an object. |
| */ |
| virtual void retain(void) = 0; |
| |
| /** |
| * Method to release (or decrease retention) of an object. |
| */ |
| virtual void release(void) = 0; |
| |
| /** |
| * Required virtual destructor. |
| */ |
| virtual ~ObjectProtocol(); |
| |
| /** |
| * Retain (increase retention of) object when copying. |
| */ |
| ObjectProtocol *copy(void); |
| |
| /** |
| * Increase retention operator. |
| */ |
| inline void operator++(void) |
| {retain();}; |
| |
| /** |
| * Decrease retention operator. |
| */ |
| inline void operator--(void) |
| {release();}; |
| }; |
| |
| /** |
| * At least with gcc, linking of stream operators was broken. This provides |
| * an auxillory class to solve the issue. |
| */ |
| class __EXPORT _character_operators |
| { |
| private: |
| inline _character_operators() {}; |
| |
| public: |
| static CharacterProtocol& print(CharacterProtocol& p, const char *s); |
| |
| static CharacterProtocol& print(CharacterProtocol& p, const char& ch); |
| |
| static CharacterProtocol& input(CharacterProtocol& p, char& ch); |
| |
| static CharacterProtocol& input(CharacterProtocol& p, String& str); |
| |
| static CharacterProtocol& print(CharacterProtocol& p, const long& value); |
| |
| static CharacterProtocol& input(CharacterProtocol& p, long& value); |
| |
| static CharacterProtocol& print(CharacterProtocol& p, const double& value); |
| |
| static CharacterProtocol& input(CharacterProtocol& p, double& value); |
| }; |
| |
| inline CharacterProtocol& operator<< (CharacterProtocol& p, const char *s) |
| {return _character_operators::print(p, s);} |
| |
| inline CharacterProtocol& operator<< (CharacterProtocol& p, const char& ch) |
| {return _character_operators::print(p, ch);} |
| |
| inline CharacterProtocol& operator>> (CharacterProtocol& p, char& ch) |
| {return _character_operators::input(p, ch);} |
| |
| inline CharacterProtocol& operator>> (CharacterProtocol& p, String& str) |
| {return _character_operators::input(p, str);} |
| |
| inline CharacterProtocol& operator<< (CharacterProtocol& p, const PrintProtocol& format) |
| {p.print(format); return p;} |
| |
| inline CharacterProtocol& operator>> (CharacterProtocol& p, InputProtocol& format) |
| {p.input(format); return p;} |
| |
| inline CharacterProtocol& operator<< (CharacterProtocol& p, const StringPager& list) |
| {p.save(&list); return p;} |
| |
| inline CharacterProtocol& operator>> (CharacterProtocol& p, StringPager& list) |
| {p.load(&list); return p;} |
| |
| inline CharacterProtocol& operator<< (CharacterProtocol& p, const long& value) |
| {return _character_operators::print(p, value);} |
| |
| inline CharacterProtocol& operator>> (CharacterProtocol& p, long& value) |
| {return _character_operators::input(p, value);} |
| |
| inline CharacterProtocol& operator<< (CharacterProtocol& p, const double& value) |
| {return _character_operators::print(p, value);} |
| |
| inline CharacterProtocol& operator>> (CharacterProtocol& p, double& value) |
| {return _character_operators::input(p, value);} |
| |
| END_NAMESPACE |
| |
| #endif |