diff options
Diffstat (limited to 'doc/API')
| -rw-r--r-- | doc/API | 142 |
1 files changed, 101 insertions, 41 deletions
@@ -11,11 +11,13 @@ of the memory usage functions. Here is the list of the functions I did override: strdup malloc realloc +calloc operator new operator delete free pipe fork +exit I did wrote some little and stupid memory functions. Maybe I'll later use dlmalloc or something like this. The other function will throw an exception @@ -26,30 +28,24 @@ the x* functions: xstrdup xmalloc xrealloc +xcalloc xfree xpipe xfork +Also, in the base class, you'll find the "printm" function, which is a little +tribute to help you printing things on the screen "ala" printf, but using the +class String instead. The first argument is the class of the message, and can +be M_BARE, M_ERROR, M_STATUS, M_WARNING, or M_INFO. The default verbosity level +is to M_ERROR, and can be changed up to M_INFO. + Class GeneralException: ---------------------- This is the generic exception that should be thrown by everything. And then -the main() function should be written like this: - -int main(int argc, char ** argv) { - try { - /* your work here */ - } - catch (GeneralException e) { - cerr << _("Main function got an exception: '") << e.GetMsg() << "'.\n"; - exit(-1); - } - catch (...) { - cerr << _("Unknow exception.\n") << endl; - exit(-1); - } -} +the "main" program will act consequently. In order to help you writing the +main function, some classes and macro have been defined. See below. Class derivated from GeneralException: @@ -65,6 +61,22 @@ TaskSwitch, will be thrown by every task that want to be suspended. You can inspire yourself from this class system to implements yours. +Class Main: +---------- + +This is a pure virtual class that should be derivated in order to properly +write the startup of a software of your own. To make it simple, you should +write a software using this scheme: + +#include <Main.h> + +CODE_BEGINS +virtual int startup() throw (GeneralException) { + printm(M_BARE, "Hello world!\n"); +} +CODE_ENDS + + Class String: ------------ @@ -89,6 +101,10 @@ They are the same as a sprintf functions, by changing the contents of the string. They return the temporary buffer used to create the string. Beware, it is constant, and there is a max size. If it exceeds, the result will be truncated. +int scanf(const char *, ...) and int scanf(const String &, ...) +They are the same as sscanf functions, and will read the contents of the string +in order to fill the arguments given. + const char * to_charp(size_t start = 0, ssize_t end = -1) const; It will copy the string into a temporary buffer. Beware, it is the same as the set function. The use of this function is depreciated. The arguments start and end @@ -96,13 +112,13 @@ specify two offsets of extraction into the string. If end == -1, then the whole string from the start offset will be copied. String extract(size_t start = 0, ssize_t end = -1) const; -It will do the same as the extract function, but it will returns a String. Yet +It will do the same as the to_charp function, but it will returns a String. Yet this function is not really good since it does call to_charp. But I'll translate it later with a better one. char * strdup(size_t = 0, ssize_t end = -1) const; -This will produce a char *, still using the terrific to_charp function. I will soon -use the extract function, I swear. +This will produce a char *, still using the "not so good" extract function. I +will clean the extract function, I swear. int to_int() const; Tries to convert the String into an int. If the string is *exactly* not an int, it @@ -155,7 +171,7 @@ It will count the number of time of the char c into the string. String & operator=(const String &); Only to be safe. Well, it will safely assign one string to another. Also safe -to do s = s even if weired. +to do s = s. String operator+(const String &) const; Concatens two strings to another third. @@ -177,12 +193,12 @@ char operator[](size_t i) const; Extract one char from the string. Like the classical char * does. Well, it will returns 0 if over the size of the string. -One note: since you can construct a String with a char * or about everything else, -you can write things like: +One note: since you can construct a String with a char * or basically everything +else, you can write things like: String s = String("Pim ") + "pam " + "poum."; Just use your imagination. -I've also overloaded the two operators << and >> for *stream: +I also overloaded the two operators << and >> for *stream: ostream & operator<<(ostream &, const String &); istream & operator>>(istream &, String &); @@ -192,7 +208,7 @@ They act as the Handles read and write function, so take a look at them. Class Regex: ----------- -Well, to use this class, please read a bit the regex man page. You have two +Well, to use this class, please read a bit the regex(7) man page. You have two construct: Regex(const String & regex, int cflags = REG_EXTENDED, int eflags = 0) @@ -205,7 +221,7 @@ You can match a regex against a string using: bool Match(const String &) const; which will return true if the string matches the regex, and false otherwise. -The construct may return a GeneralException in case of compilation error. +The construct may throw a GeneralException in case of compilation error. There is two global regex: any and empty. any.match(s) will always be true, and empty.match(s) will be true if s == "". @@ -258,7 +274,8 @@ constructs: public construct: Handle(const Handle &); The per-copy construct will duplicate the handle. If you close one, the other -will remains open. +will remains open. But beware, it will only works for childrens. You can't +create an "empty" Handle from your own. protected construct: Handle(int h); @@ -266,12 +283,24 @@ Only for childs. Used to fill the structure. virtual ssize_t read(void *buf, size_t count) throw (GeneralException); virtual ssize_t write(const void *buf, size_t count) throw (GeneralException); -Self explainatory. Will never fail so the ssize_t type is only here for -compatibility. +Self explainatory. Will never "fail" so the ssize_t type is only here for +compatibility. It will throw an exception instead. But it still can return +a smaller size than asked. + +Uint8 readU8(); +Uint16 readU16(); +Uint32 readU32(); +void writeU8(Uint8); +void writeU16(Uint16); +void writeU32(Uint32); +Some very important functions. They will always work in little endian. Even +if the machine is big endian. So on a big endian machine, it will swap the +bytes. bool IsClosed(void); Returns true if the stream is closed. The stream will self close if it does -hit end of file. +"forcibilly" hit end of file. Meaning that if you already are at the end of +the file and still try to read something, it will return you a zero void SetNonBlock(void); Set the handle non blocking. Will be *VERY* useful for the Task system. @@ -285,11 +314,20 @@ True if the handle can read. virtual bool CanWrite(); True if the handle can write. +virtual bool CanSeek(); +True ie the handle can seek. + +virtual off_t seek(off_t, int = SEEK_SET) throw (GeneralException); +Will work exactly as the fseek() function. Even using the same arguments. + +virtual off_t tell() const; +Will work as the ftell() function. + virtual String GetName(); The actual name of the Handle. virtual off_t GetSize(); -The size of the input opened file. Will clearly be removed in the future. +The size of the input opened file. -1 if not possible to get the size. virtual time_t GetModif(); Get the modification time of the file if possible. @@ -298,16 +336,19 @@ void close() throw (GeneralException); Closes the handle. int GetHandle(); -This will get the handle number. Usage deprieciated but sometime necessary. +This will get the handle number. Usage depreciated but sometime necessary. virtual bool CanWatch(); True if the handle can be watched (when non blocking) +virtual int Dup() const; +Act exactly as the dup() function. + virtual void SetZ(int level) throw (GeneralException); Set the Handle to go through libz. Compress will occurs if write() and decompress will occurs if read(). Level between 0 and 9 sets the compression ratio. SetZ(0) will do nothing. You can't revert to SetZ(0) after SetZ to a -non zero level. +non zero level. Also, will only works for unidirectionnal streams. I've got two operators: Handle & operator<<(Handle &, const String &); @@ -317,12 +358,39 @@ When <<, the string will be dumped as exactly. When >>, the string will be readed until \n or eof. The char \r is discarded. The char \n, if reached, is not stored. +A little helper function: +void copy(Handle * src, Handle * dst, ssize_t count = -1); +It will copy one whole Handle to another or only count bytes if >= 0 + Class Input: ----------- -Derivated from the Handle class. Not much to say with it, nothing added. -The construct takes the file name to open. Just watch for an IOGeneral exception. +Derivated from the Handle class. Not much to say using bare... +The construct takes the file name to open. Just watch for an IOGeneral +exception, to catch a file not found for example. + +A better thing to know is the following class... + + +Class Archive: +------------- + +This class will handle some kinds of archives types. Actually, it only handles +"proprietary" NPAQ files. Look at the source code if you want to know the +format. A helper piece of software is here to help you compressing a +directory into a .paq file. Here is how you use it: + +First you create a variable of type "Archive", like this: + +new Archive("datas.paq"); + +This one will "register" the archive named "datas.paq". So, after that, if you +create an Input handle, it will first look into the archive datas.paq to see +if your file is not in. It will only do so if the file path is relative +(ie not begining with '/' or with '?:\' (for windows...)) If your file is +found in the archive, it will be read directly and transparantly. Otherwise, +it will be a normal Input handle. Class Stdin_t: @@ -521,11 +589,3 @@ Class HttpServ: This class is a task that can be launched from the main function, and will never end. It is specially designed to create distributed applications. - - - - - - - - |