]> code.citadel.org Git - citadel.git/blobdiff - libcitadel/lib/stringbuf.c
* add autoheader for zlib and iconv detection
[citadel.git] / libcitadel / lib / stringbuf.c
index 8f6bb5b4ad1ec85069f99f66df92bd73a9d67e11..e28e9f5aff0e39e00cb23f8c0ab5d5c8dbdea482 100644 (file)
@@ -1,3 +1,4 @@
+#include "../sysdep.h"
 #include <ctype.h>
 #include <errno.h>
 #include <string.h>
 #include <stdarg.h>
 #include "libcitadel.h"
 
+#ifdef HAVE_ICONV
+#include <iconv.h>
+#endif
+
+#ifdef HAVE_ZLIB
+#include <zlib.h>
+#endif
 
+
+#ifdef HAVE_ZLIB
+#include <zlib.h>
+int ZEXPORT compress_gzip(Bytef * dest, size_t * destLen,
+                          const Bytef * source, uLong sourceLen, int level);
+#endif
+
+/**
+ * Private Structure for the Stringbuffer
+ */
 struct StrBuf {
-       char *buf;
-       long BufSize;
-       long BufUsed;
-       int ConstBuf;
+       char *buf;         /**< the pointer to the dynamic buffer */
+       long BufSize;      /**< how many spcae do we optain */
+       long BufUsed;      /**< Number of Chars used excluding the trailing \0 */
+       int ConstBuf;      /**< are we just a wrapper arround a static buffer and musn't we be changed? */
 };
 
 
+/** 
+ * \Brief Cast operator to Plain String 
+ * Note: if the buffer is altered by StrBuf operations, this pointer may become 
+ *  invalid. So don't lean on it after altering the buffer!
+ *  Since this operation is considered cheap, rather call it often than risking
+ *  your pointer to become invalid!
+ * \param Str the string we want to get the c-string representation for
+ * \returns the Pointer to the Content. Don't mess with it!
+ */
 inline const char *ChrPtr(const StrBuf *Str)
 {
        if (Str == NULL)
@@ -26,11 +53,54 @@ inline const char *ChrPtr(const StrBuf *Str)
        return Str->buf;
 }
 
+/**
+ * \brief since we know strlen()'s result, provide it here.
+ * \param Str the string to return the length to
+ * \returns contentlength of the buffer
+ */
 inline int StrLength(const StrBuf *Str)
 {
        return (Str != NULL) ? Str->BufUsed : 0;
 }
 
+/**
+ * \brief local utility function to resize the buffer
+ * \param Buf the buffer whichs storage we should increase
+ * \param KeepOriginal should we copy the original buffer or just start over with a new one
+ * \param DestSize what should fit in after?
+ */
+static int IncreaseBuf(StrBuf *Buf, int KeepOriginal, int DestSize)
+{
+       char *NewBuf;
+       size_t NewSize = Buf->BufSize * 2;
+
+       if (Buf->ConstBuf)
+               return -1;
+               
+       if (DestSize > 0)
+               while (NewSize < DestSize)
+                       NewSize *= 2;
+
+       NewBuf= (char*) malloc(NewSize);
+       if (KeepOriginal && (Buf->BufUsed > 0))
+       {
+               memcpy(NewBuf, Buf->buf, Buf->BufUsed);
+       }
+       else
+       {
+               NewBuf[0] = '\0';
+               Buf->BufUsed = 0;
+       }
+       free (Buf->buf);
+       Buf->buf = NewBuf;
+       Buf->BufSize *= 2;
+       return Buf->BufSize;
+}
+
+/**
+ * Allocate a new buffer with default buffer size
+ * \returns the new stringbuffer
+ */
 StrBuf* NewStrBuf(void)
 {
        StrBuf *NewBuf;
@@ -44,6 +114,11 @@ StrBuf* NewStrBuf(void)
        return NewBuf;
 }
 
+/** 
+ * \brief Copy Constructor; returns a duplicate of CopyMe
+ * \params CopyMe Buffer to faxmilate
+ * \returns the new stringbuffer
+ */
 StrBuf* NewStrBufDup(const StrBuf *CopyMe)
 {
        StrBuf *NewBuf;
@@ -54,9 +129,20 @@ StrBuf* NewStrBufDup(const StrBuf *CopyMe)
        NewBuf = (StrBuf*) malloc(sizeof(StrBuf));
        NewBuf->buf = (char*) malloc(CopyMe->BufSize);
        memcpy(NewBuf->buf, CopyMe->buf, CopyMe->BufUsed + 1);
+       NewBuf->BufUsed = CopyMe->BufUsed;
+       NewBuf->BufSize = CopyMe->BufSize;
+       NewBuf->ConstBuf = 0;
        return NewBuf;
 }
 
+/**
+ * \brief create a new Buffer using an existing c-string
+ * this function should also be used if you want to pre-suggest
+ * the buffer size to allocate in conjunction with ptr == NULL
+ * \param ptr the c-string to copy; may be NULL to create a blank instance
+ * \param nChars How many chars should we copy; -1 if we should measure the length ourselves
+ * \returns the new stringbuffer
+ */
 StrBuf* NewStrBufPlain(const char* ptr, int nChars)
 {
        StrBuf *NewBuf;
@@ -87,7 +173,40 @@ StrBuf* NewStrBufPlain(const char* ptr, int nChars)
        return NewBuf;
 }
 
+/**
+ * \brief Set an existing buffer from a c-string
+ * \param ptr c-string to put into 
+ * \param nChars set to -1 if we should work 0-terminated
+ * \returns the new length of the string
+ */
+int StrBufPlain(StrBuf *Buf, const char* ptr, int nChars)
+{
+       size_t Siz = Buf->BufSize;
+       size_t CopySize;
+
+       if (nChars < 0)
+               CopySize = strlen(ptr);
+       else
+               CopySize = nChars;
+
+       while (Siz <= CopySize)
+               Siz *= 2;
+
+       if (Siz != Buf->BufSize)
+               IncreaseBuf(Buf, 0, Siz);
+       memcpy(Buf->buf, ptr, CopySize);
+       Buf->buf[CopySize] = '\0';
+       Buf->BufUsed = CopySize;
+       Buf->ConstBuf = 0;
+       return CopySize;
+}
+
 
+/**
+ * \brief use strbuf as wrapper for a string constant for easy handling
+ * \param StringConstant a string to wrap
+ * \param SizeOfConstant should be sizeof(StringConstant)-1
+ */
 StrBuf* _NewConstStrBuf(const char* StringConstant, size_t SizeOfStrConstant)
 {
        StrBuf *NewBuf;
@@ -101,34 +220,10 @@ StrBuf* _NewConstStrBuf(const char* StringConstant, size_t SizeOfStrConstant)
 }
 
 
-static int IncreaseBuf(StrBuf *Buf, int KeepOriginal, int DestSize)
-{
-       char *NewBuf;
-       size_t NewSize = Buf->BufSize * 2;
-
-       if (Buf->ConstBuf)
-               return -1;
-               
-       if (DestSize > 0)
-               while (NewSize < DestSize)
-                       NewSize *= 2;
-
-       NewBuf= (char*) malloc(NewSize);
-       if (KeepOriginal)
-       {
-               memcpy(NewBuf, Buf->buf, Buf->BufUsed);
-       }
-       else
-       {
-               NewBuf[0] = '\0';
-               Buf->BufUsed = 0;
-       }
-       free (Buf->buf);
-       Buf->buf = NewBuf;
-       Buf->BufSize *= 2;
-       return Buf->BufSize;
-}
-
+/**
+ * \brief flush the content of a Buf; keep its struct
+ * \param buf Buffer to flush
+ */
 int FlushStrBuf(StrBuf *buf)
 {
        if (buf->ConstBuf)
@@ -138,6 +233,12 @@ int FlushStrBuf(StrBuf *buf)
        return 0;
 }
 
+/**
+ * \brief Release a Buffer
+ * Its a double pointer, so it can NULL your pointer
+ * so fancy SIG11 appear instead of random results
+ * \param FreeMe Pointer Pointer to the buffer to free
+ */
 void FreeStrBuf (StrBuf **FreeMe)
 {
        if (*FreeMe == NULL)
@@ -148,6 +249,11 @@ void FreeStrBuf (StrBuf **FreeMe)
        *FreeMe = NULL;
 }
 
+/**
+ * \brief Release the buffer
+ * If you want put your StrBuf into a Hash, use this as Destructor.
+ * \param VFreeMe untyped pointer to a StrBuf. be shure to do the right thing [TM]
+ */
 void HFreeStrBuf (void *VFreeMe)
 {
        StrBuf *FreeMe = (StrBuf*)VFreeMe;
@@ -158,6 +264,9 @@ void HFreeStrBuf (void *VFreeMe)
        free(FreeMe);
 }
 
+/**
+ * \brief Wrapper around atol
+ */
 long StrTol(const StrBuf *Buf)
 {
        if(Buf->BufUsed > 0)
@@ -166,6 +275,9 @@ long StrTol(const StrBuf *Buf)
                return 0;
 }
 
+/**
+ * \brief Wrapper around atoi
+ */
 int StrToi(const StrBuf *Buf)
 {
        if(Buf->BufUsed > 0)
@@ -174,28 +286,31 @@ int StrToi(const StrBuf *Buf)
                return 0;
 }
 
-int StrBufPlain(StrBuf *Buf, const char* ptr, int nChars)
+/**
+ * \brief modifies a Single char of the Buf
+ * You can point to it via char* or a zero-based integer
+ * \param ptr char* to zero; use NULL if unused
+ * \param nThChar zero based pointer into the string; use -1 if unused
+ * \param PeekValue The Character to place into the position
+ */
+long StrBufPeek(StrBuf *Buf, const char* ptr, long nThChar, char PeekValue)
 {
-       size_t Siz = Buf->BufSize;
-       size_t CopySize;
-
-       if (nChars < 0)
-               CopySize = strlen(ptr);
-       else
-               CopySize = nChars;
-
-       while (Siz <= CopySize)
-               Siz *= 2;
-
-       if (Siz != Buf->BufSize)
-               IncreaseBuf(Buf, 0, Siz);
-       memcpy(Buf->buf, ptr, CopySize);
-       Buf->buf[CopySize] = '\0';
-       Buf->BufUsed = CopySize;
-       Buf->ConstBuf = 0;
-       return CopySize;
+       if (Buf == NULL)
+               return -1;
+       if (ptr != NULL)
+               nThChar = ptr - Buf->buf;
+       if ((nThChar < 0) || (nThChar > Buf->BufUsed))
+               return -1;
+       Buf->buf[nThChar] = PeekValue;
+       return nThChar;
 }
 
+/**
+ * \brief Append a StringBuffer to the buffer
+ * \param Buf Buffer to modify
+ * \param AppendBuf Buffer to copy at the end of our buffer
+ * \param Offset Should we start copying from an offset?
+ */
 void StrBufAppendBuf(StrBuf *Buf, const StrBuf *AppendBuf, size_t Offset)
 {
        if ((AppendBuf == NULL) || (Buf == NULL))
@@ -214,6 +329,13 @@ void StrBufAppendBuf(StrBuf *Buf, const StrBuf *AppendBuf, size_t Offset)
 }
 
 
+/**
+ * \brief Append a C-String to the buffer
+ * \param Buf Buffer to modify
+ * \param AppendBuf Buffer to copy at the end of our buffer
+ * \param AppendSize number of bytes to copy; set to -1 if we should count it in advance
+ * \param Offset Should we start copying from an offset?
+ */
 void StrBufAppendBufPlain(StrBuf *Buf, const char *AppendBuf, long AppendSize, size_t Offset)
 {
        long aps;
@@ -237,12 +359,245 @@ void StrBufAppendBufPlain(StrBuf *Buf, const char *AppendBuf, long AppendSize, s
 }
 
 
-inline int StrBufNum_tokens(const StrBuf *source, char tok)
+/** 
+ * \brief Escape a string for feeding out as a URL while appending it to a Buffer
+ * \param outbuf the output buffer
+ * \param oblen the size of outbuf to sanitize
+ * \param strbuf the input buffer
+ */
+void StrBufUrlescAppend(StrBuf *OutBuf, const StrBuf *In, const char *PlainIn)
 {
-       return num_tokens(source->buf, tok);
+       const char *pch, *pche;
+       char *pt, *pte;
+       int b, c, len;
+       const char ec[] = " +#&;`'|*?-~<>^()[]{}/$\"\\";
+       int eclen = sizeof(ec) -1;
+
+       if (((In == NULL) && (PlainIn == NULL)) || (OutBuf == NULL) )
+               return;
+       if (PlainIn != NULL) {
+               len = strlen(PlainIn);
+               pch = PlainIn;
+               pche = pch + len;
+       }
+       else {
+               pch = In->buf;
+               pche = pch + In->BufUsed;
+               len = In->BufUsed;
+       }
+
+       if (len == 0) 
+               return;
+
+       pt = OutBuf->buf + OutBuf->BufUsed;
+       pte = OutBuf->buf + OutBuf->BufSize - 4; /**< we max append 3 chars at once plus the \0 */
+
+       while (pch < pche) {
+               if (pt >= pte) {
+                       IncreaseBuf(OutBuf, 1, -1);
+                       pte = OutBuf->buf + OutBuf->BufSize - 4; /**< we max append 3 chars at once plus the \0 */
+                       pt = OutBuf->buf + OutBuf->BufUsed;
+               }
+               
+               c = 0;
+               for (b = 0; b < eclen; ++b) {
+                       if (*pch == ec[b]) {
+                               c = 1;
+                               b += eclen;
+                       }
+               }
+               if (c == 1) {
+                       sprintf(pt,"%%%02X", *pch);
+                       pt += 3;
+                       OutBuf->BufUsed += 3;
+                       pch ++;
+               }
+               else {
+                       *(pt++) = *(pch++);
+                       OutBuf->BufUsed++;
+               }
+       }
+       *pt = '\0';
+}
+
+/*
+ * \brief Append a string, escaping characters which have meaning in HTML.  
+ *
+ * \param Target       target buffer
+ * \param Source       source buffer; set to NULL if you just have a C-String
+ * \param PlainIn       Plain-C string to append; set to NULL if unused
+ * \param nbsp         If nonzero, spaces are converted to non-breaking spaces.
+ * \param nolinebreaks if set, linebreaks are removed from the string.
+ */
+long StrEscAppend(StrBuf *Target, const StrBuf *Source, const char *PlainIn, int nbsp, int nolinebreaks)
+{
+       const char *aptr, *eiptr;
+       char *bptr, *eptr;
+       long len;
+
+       if (((Source == NULL) && (PlainIn == NULL)) || (Target == NULL) )
+               return -1;
+
+       if (PlainIn != NULL) {
+               aptr = PlainIn;
+               len = strlen(PlainIn);
+               eiptr = aptr + len;
+       }
+       else {
+               aptr = Source->buf;
+               eiptr = aptr + Source->BufUsed;
+               len = Source->BufUsed;
+       }
+
+       if (len == 0) 
+               return -1;
+
+       bptr = Target->buf + Target->BufUsed;
+       eptr = Target->buf + Target->BufSize - 6; /* our biggest unit to put in...  */
+
+       while (aptr < eiptr){
+               if(bptr >= eptr) {
+                       IncreaseBuf(Target, 1, -1);
+                       eptr = Target->buf + Target->BufSize - 6; 
+                       bptr = Target->buf + Target->BufUsed;
+               }
+               if (*aptr == '<') {
+                       memcpy(bptr, "&lt;", 4);
+                       bptr += 4;
+                       Target->BufUsed += 4;
+               }
+               else if (*aptr == '>') {
+                       memcpy(bptr, "&gt;", 4);
+                       bptr += 4;
+                       Target->BufUsed += 4;
+               }
+               else if (*aptr == '&') {
+                       memcpy(bptr, "&amp;", 5);
+                       bptr += 5;
+                       Target->BufUsed += 5;
+               }
+               else if (*aptr == '\"') {
+                       memcpy(bptr, "&quot;", 6);
+                       bptr += 6;
+                       Target->BufUsed += 6;
+               }
+               else if (*aptr == '\'') {
+                       memcpy(bptr, "&#39;", 5);
+                       bptr += 5;
+                       Target->BufUsed += 5;
+               }
+               else if (*aptr == LB) {
+                       *bptr = '<';
+                       bptr ++;
+                       Target->BufUsed ++;
+               }
+               else if (*aptr == RB) {
+                       *bptr = '>';
+                       bptr ++;
+                       Target->BufUsed ++;
+               }
+               else if (*aptr == QU) {
+                       *bptr ='"';
+                       bptr ++;
+                       Target->BufUsed ++;
+               }
+               else if ((*aptr == 32) && (nbsp == 1)) {
+                       memcpy(bptr, "&nbsp;", 6);
+                       bptr += 6;
+                       Target->BufUsed += 6;
+               }
+               else if ((*aptr == '\n') && (nolinebreaks)) {
+                       *bptr='\0';     /* nothing */
+               }
+               else if ((*aptr == '\r') && (nolinebreaks)) {
+                       *bptr='\0';     /* nothing */
+               }
+               else{
+                       *bptr = *aptr;
+                       bptr++;
+                       Target->BufUsed ++;
+               }
+               aptr ++;
+       }
+       *bptr = '\0';
+       if ((bptr = eptr - 1 ) && !IsEmptyStr(aptr) )
+               return -1;
+       return Target->BufUsed;
 }
 
+/*
+ * \brief Append a string, escaping characters which have meaning in HTML.  
+ * Converts linebreaks into blanks; escapes single quotes
+ * \param Target       target buffer
+ * \param Source       source buffer; set to NULL if you just have a C-String
+ * \param PlainIn       Plain-C string to append; set to NULL if unused
+ */
+void StrMsgEscAppend(StrBuf *Target, StrBuf *Source, const char *PlainIn)
+{
+       const char *aptr, *eiptr;
+       char *tptr, *eptr;
+       long len;
+
+       if (((Source == NULL) && (PlainIn == NULL)) || (Target == NULL) )
+               return ;
 
+       if (PlainIn != NULL) {
+               aptr = PlainIn;
+               len = strlen(PlainIn);
+               eiptr = aptr + len;
+       }
+       else {
+               aptr = Source->buf;
+               eiptr = aptr + Source->BufUsed;
+               len = Source->BufUsed;
+       }
+
+       if (len == 0) 
+               return;
+
+       eptr = Target->buf + Target->BufSize - 6; 
+       tptr = Target->buf + Target->BufUsed;
+       
+       while (aptr < eiptr){
+               if(tptr >= eptr) {
+                       IncreaseBuf(Target, 1, -1);
+                       eptr = Target->buf + Target->BufSize - 6; 
+                       tptr = Target->buf + Target->BufUsed;
+               }
+              
+               if (*aptr == '\n') {
+                       *tptr = ' ';
+                       Target->BufUsed++;
+               }
+               else if (*aptr == '\r') {
+                       *tptr = ' ';
+                       Target->BufUsed++;
+               }
+               else if (*aptr == '\'') {
+                       *(tptr++) = '&';
+                       *(tptr++) = '#';
+                       *(tptr++) = '3';
+                       *(tptr++) = '9';
+                       *tptr = ';';
+                       Target->BufUsed += 5;
+               } else {
+                       *tptr = *aptr;
+                       Target->BufUsed++;
+               }
+               tptr++; aptr++;
+       }
+       *tptr = '\0';
+}
+
+
+/**
+ * \brief extracts a substring from Source into dest
+ * \param dest buffer to place substring into
+ * \param Source string to copy substring from
+ * \param Offset chars to skip from start
+ * \param nChars number of chars to copy
+ * \returns the number of chars copied; may be different from nChars due to the size of Source
+ */
 int StrBufSub(StrBuf *dest, const StrBuf *Source, size_t Offset, size_t nChars)
 {
        size_t NCharsRemain;
@@ -269,26 +624,77 @@ int StrBufSub(StrBuf *dest, const StrBuf *Source, size_t Offset, size_t nChars)
        return NCharsRemain;
 }
 
-
+/**
+ * \brief sprintf like function appending the formated string to the buffer
+ * vsnprintf version to wrap into own calls
+ * \param Buf Buffer to extend by format and params
+ * \param format printf alike format to add
+ * \param ap va_list containing the items for format
+ */
 void StrBufVAppendPrintf(StrBuf *Buf, const char *format, va_list ap)
 {
+       va_list apl;
+       size_t BufSize = Buf->BufSize;
        size_t nWritten = Buf->BufSize + 1;
        size_t Offset = Buf->BufUsed;
        size_t newused = Offset + nWritten;
        
-       while (newused >= Buf->BufSize) {
+       while (newused >= BufSize) {
+               va_copy(apl, ap);
                nWritten = vsnprintf(Buf->buf + Offset, 
                                     Buf->BufSize - Offset, 
-                                    format, ap);
+                                    format, apl);
+               va_end(apl);
                newused = Offset + nWritten;
-               if (newused >= Buf->BufSize)
-                       IncreaseBuf(Buf, 1, 0);
-               else
-                       Buf->BufUsed = Offset + nWritten ;
+               if (newused >= Buf->BufSize) {
+                       IncreaseBuf(Buf, 1, newused);
+               }
+               else {
+                       Buf->BufUsed = Offset + nWritten;
+                       BufSize = Buf->BufSize;
+               }
 
        }
 }
 
+/**
+ * \brief sprintf like function appending the formated string to the buffer
+ * \param Buf Buffer to extend by format and params
+ * \param format printf alike format to add
+ * \param ap va_list containing the items for format
+ */
+void StrBufAppendPrintf(StrBuf *Buf, const char *format, ...)
+{
+       size_t BufSize = Buf->BufSize;
+       size_t nWritten = Buf->BufSize + 1;
+       size_t Offset = Buf->BufUsed;
+       size_t newused = Offset + nWritten;
+       va_list arg_ptr;
+       
+       while (newused >= BufSize) {
+               va_start(arg_ptr, format);
+               nWritten = vsnprintf(Buf->buf + Buf->BufUsed, 
+                                    Buf->BufSize - Buf->BufUsed, 
+                                    format, arg_ptr);
+               va_end(arg_ptr);
+               newused = Buf->BufUsed + nWritten;
+               if (newused >= Buf->BufSize) {
+                       IncreaseBuf(Buf, 1, newused);
+               }
+               else {
+                       Buf->BufUsed += nWritten;
+                       BufSize = Buf->BufSize;
+               }
+
+       }
+}
+
+/**
+ * \brief sprintf like function putting the formated string into the buffer
+ * \param Buf Buffer to extend by format and params
+ * \param format printf alike format to add
+ * \param ap va_list containing the items for format
+ */
 void StrBufPrintf(StrBuf *Buf, const char *format, ...)
 {
        size_t nWritten = Buf->BufSize + 1;
@@ -305,10 +711,86 @@ void StrBufPrintf(StrBuf *Buf, const char *format, ...)
 }
 
 
+/**
+ * \brief Counts the numbmer of tokens in a buffer
+ * \param Source String to count tokens in
+ * \param tok    Tokenizer char to count
+ * \returns numbers of tokenizer chars found
+ */
+inline int StrBufNum_tokens(const StrBuf *source, char tok)
+{
+       if (source == NULL)
+               return 0;
+       return num_tokens(source->buf, tok);
+}
+
+/*
+ * remove_token() - a tokenizer that kills, maims, and destroys
+ */
+/**
+ * \brief a string tokenizer
+ * \param Source StringBuffer to read into
+ * \param parmnum n'th parameter to remove
+ * \param separator tokenizer param
+ * \returns -1 if not found, else length of token.
+ */
+int StrBufRemove_token(StrBuf *Source, int parmnum, char separator)
+{
+       int ReducedBy;
+       char *d, *s;            /* dest, source */
+       int count = 0;
+
+       /* Find desired parameter */
+       d = Source->buf;
+       while (count < parmnum) {
+               /* End of string, bail! */
+               if (!*d) {
+                       d = NULL;
+                       break;
+               }
+               if (*d == separator) {
+                       count++;
+               }
+               d++;
+       }
+       if (!d) return 0;               /* Parameter not found */
+
+       /* Find next parameter */
+       s = d;
+       while (*s && *s != separator) {
+               s++;
+       }
+
+       ReducedBy = d - s;
+
+       /* Hack and slash */
+       if (*s) {
+               memmove(d, s, Source->BufUsed - (s - Source->buf));
+               Source->BufUsed -= (ReducedBy + 1);
+       }
+       else if (d == Source->buf) {
+               *d = 0;
+               Source->BufUsed = 0;
+       }
+       else {
+               *--d = 0;
+               Source->BufUsed -= (ReducedBy + 1);
+       }
+       /*
+       while (*s) {
+               *d++ = *s++;
+       }
+       *d = 0;
+       */
+       return ReducedBy;
+}
+
+
 /**
  * \brief a string tokenizer
  * \param dest Destination StringBuffer
  * \param Source StringBuffer to read into
+ * \param parmnum n'th parameter to extract
  * \param separator tokenizer param
  * \returns -1 if not found, else length of token.
  */
@@ -362,8 +844,12 @@ int StrBufExtract_token(StrBuf *dest, const StrBuf *Source, int parmnum, char se
 }
 
 
-/*
- * extract_int()  -  extract an int parm w/o supplying a buffer
+/**
+ * \brief a string tokenizer to fetch an integer
+ * \param dest Destination StringBuffer
+ * \param parmnum n'th parameter to extract
+ * \param separator tokenizer param
+ * \returns 0 if not found, else integer representation of the token
  */
 int StrBufExtract_int(const StrBuf* Source, int parmnum, char separator)
 {
@@ -380,8 +866,12 @@ int StrBufExtract_int(const StrBuf* Source, int parmnum, char separator)
                return 0;
 }
 
-/*
- * extract_long()  -  extract an long parm w/o supplying a buffer
+/**
+ * \brief a string tokenizer to fetch a long integer
+ * \param dest Destination StringBuffer
+ * \param parmnum n'th parameter to extract
+ * \param separator tokenizer param
+ * \returns 0 if not found, else long integer representation of the token
  */
 long StrBufExtract_long(const StrBuf* Source, int parmnum, char separator)
 {
@@ -399,20 +889,29 @@ long StrBufExtract_long(const StrBuf* Source, int parmnum, char separator)
 }
 
 
-/*
- * extract_unsigned_long() - extract an unsigned long parm
+/**
+ * \brief a string tokenizer to fetch an unsigned long
+ * \param dest Destination StringBuffer
+ * \param parmnum n'th parameter to extract
+ * \param separator tokenizer param
+ * \returns 0 if not found, else unsigned long representation of the token
  */
 unsigned long StrBufExtract_unsigned_long(const StrBuf* Source, int parmnum, char separator)
 {
        StrBuf tmp;
        char buf[64];
+       char *pnum;
        
        tmp.buf = buf;
        buf[0] = '\0';
        tmp.BufSize = 64;
        tmp.BufUsed = 0;
-       if (StrBufExtract_token(&tmp, Source, parmnum, separator) > 0)
-               return(atoi(buf));
+       if (StrBufExtract_token(&tmp, Source, parmnum, separator) > 0) {
+               pnum = &buf[0];
+               if (*pnum == '-')
+                       pnum ++;
+               return (unsigned long) atol(pnum);
+       }
        else 
                return 0;
 }
@@ -420,9 +919,13 @@ unsigned long StrBufExtract_unsigned_long(const StrBuf* Source, int parmnum, cha
 
 
 /**
- * \brief Input binary data from socket
+ * \brief Read a line from socket
+ * flushes and closes the FD on error
  * \param buf the buffer to get the input to
- * \param bytes the maximal number of bytes to read
+ * \param fd pointer to the filedescriptor to read
+ * \param append Append to an existing string or replace?
+ * \param Error strerror() on error 
+ * \returns numbers of chars read
  */
 int StrBufTCP_read_line(StrBuf *buf, int *fd, int append, const char **Error)
 {
@@ -457,10 +960,106 @@ int StrBufTCP_read_line(StrBuf *buf, int *fd, int append, const char **Error)
        return len - slen;
 }
 
+/**
+ * \brief Read a line from socket
+ * flushes and closes the FD on error
+ * \param buf the buffer to get the input to
+ * \param fd pointer to the filedescriptor to read
+ * \param append Append to an existing string or replace?
+ * \param Error strerror() on error 
+ * \returns numbers of chars read
+ */
+int StrBufTCP_read_buffered_line(StrBuf *Line, 
+                                StrBuf *buf, 
+                                int *fd, 
+                                int timeout, 
+                                int selectresolution, 
+                                const char **Error)
+{
+       int len, rlen;
+       int nSuccessLess = 0;
+       fd_set rfds;
+       char *pch = NULL;
+        int fdflags;
+       struct timeval tv;
+
+       if (buf->BufUsed > 0) {
+               pch = strchr(buf->buf, '\n');
+               if (pch != NULL) {
+                       rlen = 0;
+                       len = pch - buf->buf;
+                       if (len > 0 && (*(pch - 1) == '\r') )
+                               rlen ++;
+                       StrBufSub(Line, buf, 0, len - rlen);
+                       StrBufCutLeft(buf, len + 1);
+                       return len - rlen;
+               }
+       }
+       
+       if (buf->BufSize - buf->BufUsed < 10)
+               IncreaseBuf(buf, 1, -1);
+
+       fdflags = fcntl(*fd, F_GETFL);
+       if ((fdflags & O_NONBLOCK) == O_NONBLOCK)
+               return -1;
+
+       while ((nSuccessLess < timeout) && (pch == NULL)) {
+               tv.tv_sec = selectresolution;
+               tv.tv_usec = 0;
+               
+               FD_ZERO(&rfds);
+               FD_SET(*fd, &rfds);
+               if (select(*fd + 1, NULL, &rfds, NULL, &tv) == -1) {
+                       *Error = strerror(errno);
+                       close (*fd);
+                       *fd = -1;
+                       return -1;
+               }               
+               if (FD_ISSET(*fd, &rfds)) {
+                       rlen = read(*fd, 
+                                   &buf->buf[buf->BufUsed], 
+                                   buf->BufSize - buf->BufUsed - 1);
+                       if (rlen < 1) {
+                               *Error = strerror(errno);
+                               close(*fd);
+                               *fd = -1;
+                               return -1;
+                       }
+                       else if (rlen > 0) {
+                               nSuccessLess = 0;
+                               buf->BufUsed += rlen;
+                               buf->buf[buf->BufUsed] = '\0';
+                               if (buf->BufUsed + 10 > buf->BufSize) {
+                                       IncreaseBuf(buf, 1, -1);
+                               }
+                               pch = strchr(buf->buf, '\n');
+                               continue;
+                       }
+               }
+               nSuccessLess ++;
+       }
+       if (pch != NULL) {
+               rlen = 0;
+               len = pch - buf->buf;
+               if (len > 0 && (*(pch - 1) == '\r') )
+                       rlen ++;
+               StrBufSub(Line, buf, 0, len - rlen);
+               StrBufCutLeft(buf, len + 1);
+               return len - rlen;
+       }
+       return -1;
+
+}
+
 /**
  * \brief Input binary data from socket
+ * flushes and closes the FD on error
  * \param buf the buffer to get the input to
- * \param bytes the maximal number of bytes to read
+ * \param fd pointer to the filedescriptor to read
+ * \param append Append to an existing string or replace?
+ * \param nBytes the maximal number of bytes to read
+ * \param Error strerror() on error 
+ * \returns numbers of chars read
  */
 int StrBufReadBLOB(StrBuf *Buf, int *fd, int append, long nBytes, const char **Error)
 {
@@ -502,12 +1101,18 @@ int StrBufReadBLOB(StrBuf *Buf, int *fd, int append, long nBytes, const char **E
                         return rlen;
                 }
                nRead += rlen;
+               ptr += rlen;
                Buf->BufUsed += rlen;
        }
        Buf->buf[Buf->BufUsed] = '\0';
        return nRead;
 }
 
+/**
+ * \brief Cut nChars from the start of the string
+ * \param Buf Buffer to modify
+ * \param nChars how many chars should be skipped?
+ */
 void StrBufCutLeft(StrBuf *Buf, int nChars)
 {
        if (nChars >= Buf->BufUsed) {
@@ -519,6 +1124,11 @@ void StrBufCutLeft(StrBuf *Buf, int nChars)
        Buf->buf[Buf->BufUsed] = '\0';
 }
 
+/**
+ * \brief Cut the trailing n Chars from the string
+ * \param Buf Buffer to modify
+ * \param nChars how many chars should be trunkated?
+ */
 void StrBufCutRight(StrBuf *Buf, int nChars)
 {
        if (nChars >= Buf->BufUsed) {
@@ -530,8 +1140,23 @@ void StrBufCutRight(StrBuf *Buf, int nChars)
 }
 
 
-/*
- * string conversion function
+void StrBufUpCase(StrBuf *Buf) 
+{
+       char *pch, *pche;
+
+       pch = Buf->buf;
+       pche = pch + Buf->BufUsed;
+       while (pch < pche) {
+               *pch = toupper(*pch);
+               pch ++;
+       }
+}
+
+
+/**
+ * \brief unhide special chars hidden to the HTML escaper
+ * \param target buffer to put the unescaped string in
+ * \param source buffer to unescape
  */
 void StrBufEUid_unescapize(StrBuf *target, const StrBuf *source) 
 {
@@ -569,8 +1194,10 @@ void StrBufEUid_unescapize(StrBuf *target, const StrBuf *source)
 }
 
 
-/*
- * string conversion function
+/**
+ * \brief hide special chars from the HTML escapers and friends
+ * \param target buffer to put the escaped string in
+ * \param source buffer to escape
  */
 void StrBufEUid_escapize(StrBuf *target, const StrBuf *source) 
 {
@@ -685,7 +1312,7 @@ int CompressBuffer(StrBuf *Buf)
                          &compressed_len,
                          (Bytef *) Buf->buf,
                          (uLongf) Buf->BufUsed, Z_BEST_SPEED) == Z_OK) {
-               if (!ConstBuf)
+               if (!Buf->ConstBuf)
                        free(Buf->buf);
                Buf->buf = compressed_data;
                Buf->BufUsed = compressed_len;
@@ -698,6 +1325,10 @@ int CompressBuffer(StrBuf *Buf)
        return 0;
 }
 
+/**
+ * \brief decode a buffer from base 64 encoding; destroys original
+ * \param Buf Buffor to transform
+ */
 int StrBufDecodeBase64(StrBuf *Buf)
 {
        char *xferbuf;
@@ -715,8 +1346,10 @@ int StrBufDecodeBase64(StrBuf *Buf)
 }
 
 
-/*   
- * remove escaped strings from i.e. the url string (like %20 for blanks)
+/**
+ * \brief  remove escaped strings from i.e. the url string (like %20 for blanks)
+ * \param Buf Buffer to translate
+ * \param StripBlanks Reduce several blanks to one?
  */
 long StrBufUnescape(StrBuf *Buf, int StripBlanks)
 {
@@ -828,6 +1461,12 @@ int StrBufRFC2047encode(StrBuf **target, const StrBuf *source)
        return (*target)->BufUsed;;
 }
 
+/**
+ * \brief replaces all occurances of 'search' by 'replace'
+ * \param buf Buffer to modify
+ * \param search character to search
+ * \param relpace character to replace search by
+ */
 void StrBufReplaceChars(StrBuf *buf, char search, char replace)
 {
        long i;
@@ -838,3 +1477,258 @@ void StrBufReplaceChars(StrBuf *buf, char search, char replace)
                        buf->buf[i] = replace;
 
 }
+
+
+
+/*
+ * Wrapper around iconv_open()
+ * Our version adds aliases for non-standard Microsoft charsets
+ * such as 'MS950', aliasing them to names like 'CP950'
+ *
+ * tocode      Target encoding
+ * fromcode    Source encoding
+ */
+static iconv_t ctdl_iconv_open(const char *tocode, const char *fromcode)
+{
+       iconv_t ic = (iconv_t)(-1) ;
+       ic = iconv_open(tocode, fromcode);
+       if (ic == (iconv_t)(-1) ) {
+               char alias_fromcode[64];
+               if ( (strlen(fromcode) == 5) && (!strncasecmp(fromcode, "MS", 2)) ) {
+                       safestrncpy(alias_fromcode, fromcode, sizeof alias_fromcode);
+                       alias_fromcode[0] = 'C';
+                       alias_fromcode[1] = 'P';
+                       ic = iconv_open(tocode, alias_fromcode);
+               }
+       }
+       return(ic);
+}
+
+
+#ifdef HAVE_ICONV
+
+static inline char *FindNextEnd (StrBuf *Buf, char *bptr)
+{
+       char * end;
+       /* Find the next ?Q? */
+       if (Buf->BufUsed - (bptr - Buf->buf)  < 6)
+               return NULL;
+
+       end = strchr(bptr + 2, '?');
+
+       if (end == NULL)
+               return NULL;
+
+       if ((Buf->BufUsed - (end - Buf->buf) > 3) &&
+           ((*(end + 1) == 'B') || (*(end + 1) == 'Q')) && 
+           (*(end + 2) == '?')) {
+               /* skip on to the end of the cluster, the next ?= */
+               end = strstr(end + 3, "?=");
+       }
+       else
+               /* sort of half valid encoding, try to find an end. */
+               end = strstr(bptr, "?=");
+       return end;
+}
+
+
+/*
+ * Handle subjects with RFC2047 encoding such as:
+ * =?koi8-r?B?78bP0s3Mxc7JxSDXz9rE1dvO2c3JINvB0sHNySDP?=
+ */
+void StrBuf_RFC822_to_Utf8(StrBuf **Buf, const StrBuf* DefaultCharset) {
+       StrBuf *TmpBuf, *ConvertBuf, *ConvertBuf2;
+       StrBuf StaticBuf;
+       char *start, *end, *next, *nextend, *ptr;
+       char charset[128];
+       char encoding[16];
+       iconv_t ic = (iconv_t)(-1) ;
+       char *ibuf;                     /**< Buffer of characters to be converted */
+       char *obuf;                     /**< Buffer for converted characters */
+       size_t ibuflen;                 /**< Length of input buffer */
+       size_t obuflen;                 /**< Length of output buffer */
+       char *isav;                     /**< Saved pointer to input buffer */
+       
+       const char *eptr;
+       int passes = 0;
+       int i, len, delta;
+       int illegal_non_rfc2047_encoding = 0;
+
+       /* Sometimes, badly formed messages contain strings which were simply
+        *  written out directly in some foreign character set instead of
+        *  using RFC2047 encoding.  This is illegal but we will attempt to
+        *  handle it anyway by converting from a user-specified default
+        *  charset to UTF-8 if we see any nonprintable characters.
+        */
+       TmpBuf = NewStrBufPlain(NULL, StrLength(*Buf));
+
+       len = StrLength(*Buf);
+       for (i=0; i<(*Buf)->BufUsed; ++i) {
+               if (((*Buf)->buf[i] < 32) || ((*Buf)->buf[i] > 126)) {
+                       illegal_non_rfc2047_encoding = 1;
+                       break;
+               }
+       }
+
+       if (illegal_non_rfc2047_encoding) {
+               if ( (strcasecmp(ChrPtr(DefaultCharset), "UTF-8")) && 
+                    (strcasecmp(ChrPtr(DefaultCharset), "us-ascii")) ) {
+                       ic = ctdl_iconv_open("UTF-8", ChrPtr(DefaultCharset));
+                       if (ic != (iconv_t)(-1) ) {
+                               ibuf = (*Buf)->buf;
+                               obuf = TmpBuf->buf;
+                               ibuflen = (*Buf)->BufUsed;
+                               obuflen = TmpBuf->BufSize;
+
+                               iconv(ic, &ibuf, &ibuflen, &obuf, &obuflen);
+                               TmpBuf->BufUsed = TmpBuf->BufSize - obuflen;
+                               TmpBuf->buf[TmpBuf->BufUsed] = '\0';
+
+                               FreeStrBuf(Buf);
+                               *Buf = TmpBuf;
+                               TmpBuf = NewStrBufPlain(NULL, StrLength(*Buf));
+
+                               iconv_close(ic);
+                       }
+               }
+       }
+
+       /* pre evaluate the first pair */
+       nextend = end = NULL;
+       len = StrLength(*Buf);
+       start = strstr((*Buf)->buf, "=?");
+       eptr = (*Buf)->buf + (*Buf)->BufUsed;
+       if (start != NULL) 
+               end = FindNextEnd (*Buf, start);
+
+       while ((start != NULL) && 
+              (end != NULL) && 
+              (start < eptr) && 
+              (end < eptr))
+       {
+               next = strstr(end, "=?");
+               nextend = NULL;
+               if ((next != NULL) && 
+                   (next < eptr))
+                       nextend = FindNextEnd(*Buf, next);
+               if (nextend == NULL)
+                       next = NULL;
+
+               /* did we find two partitions */
+               if ((next != NULL) && 
+                   ((next - end) > 2))
+               {
+                       ptr = end + 2;
+                       while ((ptr < next) && 
+                              (isspace(*ptr) ||
+                               (*ptr == '\r') ||
+                               (*ptr == '\n') || 
+                               (*ptr == '\t')))
+                               ptr ++;
+                       /* did we find a gab just filled with blanks? */
+                       if (ptr == next)
+                       {
+                               memmove (end + 2,
+                                        next,
+                                        len - (next - start));
+                               
+                               /* now terminate the gab at the end */
+                               delta = (next - end) - 2;
+                               (*Buf)->BufUsed -= delta;
+                               (*Buf)->buf[(*Buf)->BufUsed] = '\0';
+
+                               /* move next to its new location. */
+                               next -= delta;
+                               nextend -= delta;
+                       }
+               }
+               /* our next-pair is our new first pair now. */
+               start = next;
+               end = nextend;
+       }
+
+       ConvertBuf = NewStrBufPlain(NULL, StrLength(*Buf));
+       ConvertBuf2 = NewStrBufPlain(NULL, StrLength(*Buf));
+       /* Now we handle foreign character sets properly encoded
+        * in RFC2047 format.
+        */
+       while (start=strstr((*Buf)->buf, "=?"), 
+              end=FindNextEnd((*Buf), ((start != NULL)? start : (*Buf)->buf)),
+                              ((start != NULL) && 
+                               (end != NULL) && 
+                               (end > start)) )
+       {
+               StaticBuf.buf = start;
+               StaticBuf.BufUsed = (*Buf)->BufUsed - ((*Buf)->buf - start);
+               StaticBuf.BufSize = (*Buf)->BufSize - ((*Buf)->buf - start);
+               extract_token(charset, start, 1, '?', sizeof charset);
+               extract_token(encoding, start, 2, '?', sizeof encoding);
+               StrBufExtract_token(ConvertBuf, &StaticBuf, 3, '?');
+
+               if (!strcasecmp(encoding, "B")) {       /**< base64 */
+                       ConvertBuf2->BufUsed = CtdlDecodeBase64(ConvertBuf2->buf, 
+                                                               ConvertBuf->buf, 
+                                                               ConvertBuf->BufUsed);
+               }
+               else if (!strcasecmp(encoding, "Q")) {  /**< quoted-printable */
+                       long pos;
+                       
+                       pos = 0;
+                       while (pos < ConvertBuf->BufUsed)
+                       {
+                               if (ConvertBuf->buf[pos] == '_') 
+                                       ConvertBuf->buf[pos] = ' ';
+                               pos++;
+                       }
+
+                       ConvertBuf2->BufUsed = CtdlDecodeQuotedPrintable(
+                               ConvertBuf2->buf, 
+                               ConvertBuf->buf,
+                               ConvertBuf->BufUsed);
+               }
+               else {
+                       StrBufAppendBuf(ConvertBuf2, ConvertBuf, 0);
+               }
+
+               ic = ctdl_iconv_open("UTF-8", charset);
+               if (ic != (iconv_t)(-1) ) {
+                       ibuf = ConvertBuf2->buf;
+                       obuf = ConvertBuf->buf;
+                       ibuf = ConvertBuf2->buf;
+                       obuflen = ConvertBuf->BufSize;
+                       ibuflen = ConvertBuf2->BufUsed;
+
+                       iconv(ic, &ibuf, &ibuflen, &obuf, &obuflen);
+                       ConvertBuf->BufUsed = ConvertBuf->BufSize - obuflen;
+                       ConvertBuf->buf[ConvertBuf->BufUsed] = '\0';
+
+                       StrBufAppendBuf(TmpBuf, ConvertBuf, 0);
+                       iconv_close(ic);
+               }
+               else {
+
+                       StrBufAppendBufPlain(TmpBuf, HKEY("(unreadable)"), 0);
+               }
+
+               free(isav);
+
+               /*
+                * Since spammers will go to all sorts of absurd lengths to get their
+                * messages through, there are LOTS of corrupt headers out there.
+                * So, prevent a really badly formed RFC2047 header from throwing
+                * this function into an infinite loop.
+                */
+               ++passes;
+               if (passes > 20)  { 
+                       FreeStrBuf(Buf);
+                       *Buf = TmpBuf;
+                       return;
+               }
+       }
+       FreeStrBuf(Buf);
+       *Buf = TmpBuf;
+}
+#else
+void StrBuf_RFC822_to_Utf8(StrBuf **Buf, const StrBuf* DefaultCharset) {};
+
+#endif