/*

    File: TextUtilities.h

    Description:

        Routines for simple string-of-bytes oriented memory manipulation.  

    Copyright:

        Copyright (c) 2003 Apple Computer, Inc. All rights reserved.

    Disclaimer:

        IMPORTANT:  This Apple software is supplied to you by Apple Computer, Inc.

        ("Apple") in consideration of your agreement to the following terms, and your

        use, installation, modification or redistribution of this Apple software

        constitutes acceptance of these terms.  If you do not agree with these terms,

        please do not use, install, modify or redistribute this Apple software.

        In consideration of your agreement to abide by the following terms, and subject

        to these terms, Apple grants you a personal, non-exclusive license, under AppleÕs

        copyrights in this original Apple software (the "Apple Software"), to use,

        reproduce, modify and redistribute the Apple Software, with or without

        modifications, in source and/or binary forms; provided that if you redistribute

        the Apple Software in its entirety and without modifications, you must retain

        this notice and the following text and disclaimers in all such redistributions of

        the Apple Software.  Neither the name, trademarks, service marks or logos of

        Apple Computer, Inc. may be used to endorse or promote products derived from the

        Apple Software without specific prior written permission from Apple.  Except as

        expressly stated in this notice, no other rights or licenses, express or implied,

        are granted by Apple herein, including but not limited to any patent rights that

        may be infringed by your derivative works or by other works in which the Apple

        Software may be incorporated.

        The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO

        WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED

        WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR

        PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN

        COMBINATION WITH YOUR PRODUCTS.

        IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR

        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE

        GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

        ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION

        OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT

        (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN

        ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    Change History (most recent first):

        Wed, Aug 27, 2003 -- created

*/

#ifndef __TEXT_UTILITIES__

#define __TEXT_UTILITIES__

#include <ApplicationServices/ApplicationServices.h>

#include <stdarg.h>

    /* some simple string of bytes manipulation routines */

    /* compare two buffers byte by byte returning a integer value

    of -1, 0, or 1 if the first buffer is less than, equal to, or

    greater than the second buffer.  if caseSensitive is false, then

    it is assumed that the two buffers contain ascii characters and

    case insensitive comparisons are used.  */

long CompareTextBuffers(

            unsigned char* bufferA, long bufferAlen, 

            unsigned char* bufferB, long bufferBlen,

            Boolean caseSensitive);

    /* SearchTextBuffer searches through the buffer for pattern

    starting at startingPos.  If pos is not NULL and a match is found,

    then the long integer at that address is set to the location of

    the match.  if caseSensitive is false, then it is assumed that

    the two buffers contain ascii characters and case insensitive

    comparisons are used.  uses a Boyer-Moore search algorithm. */

Boolean SearchTextBuffer(unsigned char *buffer, long bufferLength, 

            unsigned char *pattern, long patternLength,

            long startingPos, Boolean caseSensitive, long* pos);

    /* TextReference is used to refer to a section of a buffer */

typedef struct {

    unsigned char *strp;

    long len;

} TextReference, *TextReferencePtr;

    /* SetTextRefFromCString initializes a TextReference record to

    reference the characters in a c style string */

void SetTextRefFromCString(TextReference *tr, char* cstring);

    /* SetTextRefFromCString initializes a TextReference record to

    reference the characters stored in a block of memory referenced

    by a macintosh memory manager handle.  it does not lock the handle,

    so make sure you lock the handle before using this call.  If the

    handle moves in memory, the TextReference will not be valid. */

void SetTextRefFromHandle(TextReference *tr, Handle h);

    /* A LongTextString structure begins with a TextReference structure

    on purpose so that a LongTextStringPtr can be coerced to a TextReferencePtr

    and used without any problems.  LongTextString records are allocated in

    the heap and contain an array of characters that is described by the

    TextReference at the beginning of the record.*/

typedef struct {

    TextReference text;

    unsigned char characters[1]; /* variable in length */

} LongTextString, *LongTextStringPtr;

    /* SetTextRefFromLongTextString initializes a TextReference so that it

    references the text stored in a LongTextString structure*/

void SetTextRefFromLongTextString(TextReference *tr, LongTextStringPtr textBuffer);

    /* GetDescTextData is a utility routine that returns the data stored

    in a AEDesc record.  The pointer is allocated on the heap. */

OSErr GetDescTextData(AEDesc *theDesc, Ptr *theData, Size *theLength);

    /* GetLongTextStringFromBuffer creates a new LongTextString containing

    a copy of the data referenced in the buffer.  */

OSErr GetLongTextStringFromBuffer(unsigned char *buffer, long bufferLength, 

            LongTextStringPtr *theString);

    /* GetLongTextStringFromDesc creates a new LongTextString containing a copy

    of the data stored in the AEDesc record. */

OSErr GetLongTextStringFromDesc(AEDesc *theDesc, LongTextStringPtr *theString);

    /* GetLongTextStringFromParam creates a new LongTextString containing a copy

    of the data stored in a particular parameter of an Apple event record. */

OSErr GetLongTextStringFromParam(

            const AppleEvent *appleEvt, 

            AEKeyword theAEKeyword, 

            LongTextStringPtr *theString);

    /* GetLongTextStringListElt creates a new LongTextString containing a copy

    of the data stored in a particular element of an AEDescList structure.  index

    is a value ranging from 1 through n, where n is the number of items in the list. */

OSErr GetLongTextStringListElt(

            const AEDescList *theAEDescList, 

            long index, 

            LongTextStringPtr *theString);

    /* CompareLongTextStringListElt calls CompareTextBuffers to

    compare two LongTextStrings returning CompareTextBuffers' result

    to the caller. */

long CompareLongTextStringListElt(

            LongTextStringPtr a,

            LongTextStringPtr b,

            Boolean caseSensitive);

    /* CompareLongTextStringListEltToBuffer calls CompareTextBuffers to

    compare a LongTextString to a buffer returning CompareTextBuffers' result

    to the caller. */

long CompareLongTextStringListEltToBuffer(

            LongTextStringPtr a, 

            unsigned char* buffer, long bufferlen,

            Boolean caseSensitive);

    /* FindLongTextString searches a LongTextString for a pattern

    by calling SearchTextBuffer, returning SearchTextBuffer's result

    to the caller. */

Boolean FindLongTextString(LongTextStringPtr theString, 

            unsigned char *pattern, long patternLength,

            long startingPos, Boolean caseSensitive, long* pos);

    /* VSPrintfLongTextString is like vsprintf, but it accumulates its

    result into a LongTextString.  NULL is returned if there is an error.

    calls VSPrintfTextBuffer. */

LongTextStringPtr VSPrintfLongTextString(const char *fmt, va_list args);

    /* PrintfLongTextString is like printf, but it accumulates its

    result into a LongTextString.  NULL is returned if there is an error.

    calls VSPrintfTextBuffer.  */

LongTextStringPtr PrintfLongTextString(const char *fmt, ...);

    /* DisposeLongTextString releases the storage allocated for a LongTextString. */

void DisposeLongTextString(LongTextStringPtr theString);

    /* TextOutputBuffer is used for accumulating strings of bytes into a single

    contiguous buffer of data.  A sequence of TextBufferWrite calls can

    be used to stash chunks of bytes into a TextOutputBuffer, and later the buffer

    can be retrieved as one single contiguous memory block.  A TextOutputBuffer is

    made up of a linked list of TextBuffer structures that contain the actual

    data.  These are allocated as required by TextBufferWrite.  */

typedef struct TextBuffer TextBuffer;

typedef TextBuffer *TextBufferPtr;

struct TextBuffer {

    TextBufferPtr next; /* the next buffer int he linked list */

    TextReference data; /* a reference describing the data stored in this buffer */

    TextReference buffer; /* a reference describing the available space in this buffer */

    unsigned char characters[1]; /* variable, bytes allocated for storage */

};

typedef struct {

    TextBufferPtr first, last; /* a linked list of TextBuffers */

} TextOutputBuffer;

    /* InitTextBuffer initializes a TextOutputBuffer so it is ready

    for use. This call simply initialized the linked list of buffers

    to an empty list. */ 

void InitTextBuffer(TextOutputBuffer *theBuffer);

    /* DisposeTextBuffer releases all of the TextBuffers stored in

    the TextOutputBuffer's linked list of buffers.  */

OSErr DisposeTextBuffer(TextOutputBuffer *theBuffer);

    /* TextBufferWrite accumulates the bytes into the TextOutputBuffer. */

OSErr TextBufferWrite(TextOutputBuffer *theBuffer, void* data, long len);

    /* VSPrintfTextBuffer is like vsprintf, but it outputs to a TextOutputBuffer,

    and it understands a few additinal types of parameters.  These parameters are:

    '%M' the parameter is a pointer (LongTextStringPtr/TextReferencePtr) and the

        resulting data will be encoded as html text.  ie, it will have the appropriate

        entity tags as required.

    '%N' the parameter is a pointer (LongTextStringPtr/TextReferencePtr) and the

        resulting data will be encoded as html text.  ie, it will have the appropriate

        entity tags as required.  Also, <BR> tags will be inserted when ever a \n or \r

        character is encountered.

    '%T' or '%L' the parameter is a pointer (LongTextStringPtr/TextReferencePtr).  The

        data referenced by the TextReference is copied into the output stream.

    '%H' the parameter is a macintosh memory manager handle.  the data from the block

        of memory referenced by the handle will be copied into the output stream.  no

        need to lock the handle, it will be locked as needed.

    calls TextBufferWrite.

    */

OSErr VSPrintfTextBuffer(TextOutputBuffer *theBuffer, const char *fmt, va_list args);

    /* PrintfTextBuffer calls VSPrintfTextBuffer */

OSErr PrintfTextBuffer(TextOutputBuffer *theBuffer, const char *fmt, ...);

    /* VSPrintfAsXML is like VSPrintfTextBuffer, but all of the resulting output

    is converted to xml text.  i.e. <, &, >, ", and ' entity

    characters are substitued for '<', '&', '>', '"', and '\'' before the output

    is added to the TextOutputBuffer. calls TextBufferWrite. */

OSErr VSPrintfAsXML(TextOutputBuffer *theBuffer, const char *fmt, va_list args);

    /* PrintfAsXML calls VSPrintfAsXML */

OSErr PrintfAsXML(TextOutputBuffer *theBuffer, const char *fmt, ...);

    /* TextBufferSize returns the size in bytes of the textOutputBuffer.  This will

    include the number of bytes accumulated by calls to TextBufferWrite. */

OSErr TextBufferSize(TextOutputBuffer *theBuffer, long *bytecount);

    /* TextBufferLongTextString allocates and returns a LongTextString containing

    all of the bytes accumulated in the TextOutputBuffer. */

OSErr TextBufferLongTextString(TextOutputBuffer *theBuffer, LongTextStringPtr *theText);

    /* TextBufferDataPtr allocates and returns a new pointer (calling NewPtr) containing

    all of the bytes accumulated in the TextOutputBuffer. */

OSErr TextBufferDataPtr(TextOutputBuffer *theBuffer, Ptr *theData);

    /* CopyTextBufferData the data accumulated in the TextOutputBuffer into a destination buffer.

    If actLength is not NULL, then the number of bytes actually copied will be returned in *actLength.

    CopyTextBufferData returns true if all of the bytes in the TextOutputBuffer were copied.  */

Boolean CopyTextBufferData(TextOutputBuffer *theBuffer, long offset, void* dstBuffer, long reqLength, long *actLength);

    /* EncodeXMLTextStringProc encodes the string in textBuffer as XML encoded

    text with <, &, >, ", and ' entity characters substitued

    for '<', '&', '>', '"', and '\'' characters.  The encoded text is accumulated

    in a TextOutputBuffer.   */

OSErr EncodeXMLTextStringProc(LongTextStringPtr textBuffer, TextOutputBuffer *theBuffer);

    /* EncodeHTMLTextStringProc encodes the string in textBuffer as XML encoded

    text with special characters encoded as html entities.  The encoded text is

    accumulated in a TextOutputBuffer.   */

OSErr EncodeHTMLTextStringProc(LongTextStringPtr textBuffer, Boolean addLineBreaks, TextOutputBuffer *theBuffer);

    /* StripHTMLCommentsProc removes any HTML style comments from the text accumulating

    the result into the TextOutputBuffer.   */

OSErr StripHTMLCommentsProc(LongTextStringPtr textBuffer, TextOutputBuffer *theBuffer);

    /* DecodeXMLStringToBuffer decodes a buffer containing XML encoded text (i.e. entity

    chars created by EncodeXMLTextStringProc) accumulating the result into a TextOutputBuffer. */

OSErr DecodeXMLStringToBuffer(unsigned char* buffer, long length, TextOutputBuffer *theBuffer);

    /* DecodeHTMLStringToBuffer decodes a buffer containing HTML encoded text (i.e. entity

    chars created by EncodeHTMLTextStringProc) accumulating the result into a TextOutputBuffer. */

OSErr DecodeHTMLStringToBuffer(unsigned char* buffer, long length, TextOutputBuffer *theBuffer);

    /* DecodeHTMLString calls DecodeHTMLStringToBuffer to decode a html string, then it

    returns the decoded data in a LongTextString. */

LongTextStringPtr DecodeHTMLString(unsigned char* buffer, long length);

    /* The following routines operate on "delimited sections".  A "delimited section",

    is a part of a string delimited by a starting pattern and an ending pattern.  For

    example, in the following string:

        <!-- Section One --> <!-- Section Two -->  <!-- Section Three -->

    there are three "delimited sections" each of which is delimited by the

    starting pattern "<!--" and the ending pattern "-->".  */

    /* CountDelimitedSectionsProc counts the number of delimited sections in the textBuffer

    that are delimited by startPat and endPat.  If caseSensitive is false, then case

    insensitive comparisons are used.   The number of delimited sections found is returned

    in *count.  */

OSErr CountDelimitedSectionsProc(

                LongTextStringPtr textBuffer, /* the string */

                LongTextStringPtr startPat,  /* starting pattern */

                LongTextStringPtr endPat, /* ending pattern */

                Boolean caseSensitive,  /* use case sensitive comparisons? */

                long *count); 

    /* LocateAllDelimitedSectionsProc returns an array of TextReference records referencing

    the contents of all of the delimited sections found in the text string.  For example,

    given following parameters:

        textBuffer: '<!-- Section One --> <!-- Section Two -->  <!-- Section Three -->'

        startPat: '<!--'

        endPat: '-->'

    we would expect LocateAllDelimitedSectionsProc to return an array of TextReferences

    that refer to the orignal string as follows:

        theSections[0] -> ' Section One '

        theSections[1] -> ' Section Two '

        theSections[2] -> ' Section Three '

    *count is set to the number of delimited sections found. */

OSErr LocateAllDelimitedSectionsProc(

                TextReferencePtr textBuffer,

                TextReferencePtr startPat, 

                TextReferencePtr endPat, 

                Boolean caseSensitive, 

                long *count,

                TextReferencePtr *theSections);

    /* GetAllDelimitedSectionsProc calls LocateAllDelimitedSectionsProc coercing all of the

    LongTextStringPtrs to TextReferencePtrs as appropriate. */

OSErr GetAllDelimitedSectionsProc(

                LongTextStringPtr textBuffer,

                LongTextStringPtr startPat, 

                LongTextStringPtr endPat, 

                Boolean caseSensitive, 

                long *count,

                TextReferencePtr *theSections);

    /* LocateDelimitedSectionProc returns two TextReference records referencing

    the nth occurence of a delimited section found in the text string.  For example,

    given following parameters:

        textBuffer: '<!-- Section One --> <!-- Section Two -->  <!-- Section Three -->'

        startPat: '<!--'

        endPat: '-->'

        sectionNumber: 1 -- sections are numbered starting at zero

    we would expect LocateDelimitedSectionProc to return the following TextReferences

    that refer to the orignal string:

        sectionText -> ' Section Two '

        outerBounds -> '<!-- Section Two -->'

    *count is set to the number of delimited sections found. */

OSErr LocateDelimitedSectionProc(

                TextReferencePtr textBuffer,

                TextReferencePtr startPat, 

                TextReferencePtr endPat, 

                Boolean caseSensitive,

                long sectionNumber,

                TextReference* sectionText, 

                TextReference* outerBounds);

    /* GetDelimitedSectionProc returns the contents of the nth delimited section

    in a LongTextString allocated on the heap.  It calls LocateDelimitedSectionProc

    to find the text, then it allocates the resulting string by calling

    GetLongTextStringFromBuffer.  Call DisposeLongTextString to release that memory

    when you are done using the string.  */

OSErr GetDelimitedSectionProc(

                LongTextStringPtr textBuffer,

                LongTextStringPtr startPat, 

                LongTextStringPtr endPat, 

                Boolean caseSensitive,

                long sectionNumber,

                LongTextStringPtr *sectionText);

    /* SimpleGetDelimitedSection is like GetDelimitedSectionProc except it

    is simpler to use in C programs because it accepts c-style strings for

    the starting and ending patterns.  */

OSErr SimpleGetDelimitedSection(

                LongTextStringPtr textBuffer,

                char* startingString, 

                char* endingString, 

                Boolean caseSensitive,

                long sectionNumber,

                LongTextStringPtr *sectionText);

    /* ChangeDelimetedSection returns a newly allocated LongTextString that is

    a copy of the string referenced in the textBuffer with the

    contents of the nth delimited section replaced with the string

    referenced by newText.  

    For example, given these parameters:

        textBuffer: '<!-- Section One --> <!-- Section Two -->  <!-- Section Three -->'

        startPat: '<!--'

        endPat: '-->'

        newText: ' hello world '

        caseSensitive: true

        sectionNumber: 1 -- sections are numbered starting at zero

    ChangeDelimetedSection would return a new LongTextString containing the following

    string:

        revisedText: '<!-- Section One --> <!-- hello world -->  <!-- Section Three -->'

    Call DisposeLongTextString to release that memory

    when you are done using the resulting string.  */

OSErr ChangeDelimetedSection(

                TextReferencePtr textBuffer,

                TextReferencePtr startPat, 

                TextReferencePtr endPat, 

                TextReferencePtr newText, 

                Boolean caseSensitive,

                long sectionNumber,

                LongTextStringPtr *revisedText);

    /* SetDelimitedSectionProc is the same as ChangeDelimetedSection except it

    accepts LongTextStringPtrs as parameters rather than TextReferencePtrs.  It

    does the necessary coercions and calls ChangeDelimetedSection.  it's a convenience

    routine. */

OSErr SetDelimitedSectionProc(

                LongTextStringPtr textBuffer,

                LongTextStringPtr startPat, 

                LongTextStringPtr endPat, 

                LongTextStringPtr newText, 

                Boolean caseSensitive,

                long sectionNumber,

                LongTextStringPtr *revisedText);

    /* SimpleSetDelimitedSection is the same as ChangeDelimetedSection, except it

    accepts c-style strings for the starting and ending patterns.  it is a convenience

    routine for use in c programs. */

OSErr SimpleSetDelimitedSection(

                LongTextStringPtr textBuffer,

                char* startingString, 

                char* endingString, 

                LongTextStringPtr newText,

                Boolean caseSensitive,

                long sectionNumber,

                LongTextStringPtr *revisedText);

    /* DeleteDelimitedSectionProc returns a newly allocated LongTextString that is

    a copy of the string referenced in the textBuffer with the

    nth delimited section (including the starting ane ending patterns) removed.  

    For example, given these parameters:

        textBuffer: '<!-- Section One --> <!-- Section Two -->  <!-- Section Three -->'

        startPat: '<!--'

        endPat: '-->'

        caseSensitive: true

        sectionNumber: 1 -- sections are numbered starting at zero

    DeleteDelimitedSectionProc would return a new LongTextString containing the following

    string:

        revisedText: '<!-- Section One -->   <!-- Section Three -->'

    Call DisposeLongTextString to release that memory

    when you are done using the resulting string.  */

OSErr DeleteDelimitedSectionProc(

                TextReferencePtr textBuffer,

                TextReferencePtr startPat, 

                TextReferencePtr endPat, 

                Boolean caseSensitive,

                long sectionNumber,

                LongTextStringPtr *revisedText);

    /* RemoveDelimitedSectionProc is a convenience routine that calls

    DeleteDelimitedSectionProc.  The only difference is that this routine

    accepts LongTextStringPtrs rather than TextReferencePtrs. */

OSErr RemoveDelimitedSectionProc(

                LongTextStringPtr textBuffer,

                LongTextStringPtr startPat, 

                LongTextStringPtr endPat, 

                Boolean caseSensitive,

                long sectionNumber,

                LongTextStringPtr *revisedText);

    /* form letter routines.

    these routines provide a simple search and replace api suitable for

    implementing form letter style filtering of data.  the caller provides

    a text string (the form letter) and an array of pattern/replacement

    pairs.  In processing, starting with the longest pattern, every occurence

    of every pattern is replaced with it's corresponding replacement string.

    Once the search and replace operation is complete, the results are accumulated

    in a TextOutputBuffer.  For example, given the form letter string:

    ----

        Dear customer_name,

        Thank you for purchasing your new product_name on date_string.

        If you encounter any difficulties with your new product_name, then

        please contact us at our service department.

        sender_name

    ----

    and the following pattern/replacement table:

        customer_name -> 'Jane Doe'

        product_name -> 'Form Letter Maker'

        sender_name -> 'J. Formwaver'

    Then the following output would be accumulated in the TextOutputBuffer:

    ----

        Dear Jane Doe,

        Thank you for purchasing your new Form Letter Maker on date_string.

        If you encounter any difficulties with your new Form Letter Maker, then

        please contact us at our service department.

        J. Formwaver

    ----

     */

    /* FormLetterElement records are used to store pattern/replacement pairs.

    You pass an array of FormLetterElements to the form letter routines.  */

typedef struct {

    TextReference pattext; /* the search pattern */

    TextReference reptext; /* the replacement text */

} FormLetterElement, *FormLetterElementTable;

    /* AccumulateFormLetter accumulates output into a TextOutputBuffer using

    the textBuffer and the pattern/replacement pairs in the repsTable.  if

    caseSensitive is true, then case sensitive comparisons are used. */

OSErr AccumulateFormLetter(

                TextOutputBuffer *theBuffer,

                TextReferencePtr textBuffer,

                FormLetterElementTable repsTable, 

                long repsTableLength, 

                Boolean caseSensitive);

    /* FillFormLetter calls AccumulateFormLetter to accumulates output

    into a TextOutputBuffer using the textBuffer and the pattern/replacement

    pairs in the repsTable, and then it returns the accumulated data in a

    LongTextString. Call DisposeLongTextString to release that memory when

    you are done using the resulting string.*/

OSErr FillFormLetter(

                TextReferencePtr textBuffer,

                FormLetterElementTable repsTable, 

                long repsTableLength, 

                Boolean caseSensitive,

                LongTextStringPtr *revistedText);

    /* FormLetterReplacementProc is the same as FillFormLetter, except it accepts

    a LongTextStringPtr rather than a TextReferencePtr to the form letter string.*/

OSErr FormLetterReplacementProc(

                LongTextStringPtr textBuffer,

                FormLetterElementTable repsTable, 

                long repsTableLength, 

                Boolean caseSensitive,

                LongTextStringPtr *revistedText);

    /* CGI support routines */

    /* DecodeCGIStringToBuffer decodes a cgi string replacing '+'s with spaces,

    and %XX sequences with characters accumulating the result in a TextOutputBuffer.  */

OSErr DecodeCGIStringToBuffer(unsigned char* buffer, long length, TextOutputBuffer *theBuffer);

    /* EncodeStringToCGIBuffer encodes a string in a way suitable for placement in

    a cgi post request.  spaces are replaced with '+'s, other special characters are

    replaced with %XX sequences.  if specialSpaces is true, then spaces are encoded

    as '+' signs, otherwise they are encoded as %XX sequences.  */

OSErr EncodeStringToCGIBuffer(unsigned char* buffer, long length, Boolean specialSpaces, TextOutputBuffer *theBuffer);

    /* DecodeCGIStringToString and EncodeStringToCGIString are convenience routines that

    call DecodeCGIStringToBuffer and EncodeStringToCGIBuffer.  The only difference is that

    they package up the resulting data in a LongTextString.  Call DisposeLongTextString to

    release that memory when you are done using the resulting string. */

LongTextStringPtr DecodeCGIStringToString(unsigned char* buffer, long length);

LongTextStringPtr EncodeStringToCGIString(unsigned char* buffer, long length, Boolean specialSpaces);

    /* EncodeTextAsURLTextToBuffer encodes a string in a way that is appropriate for

    placing the resulting string in a URL.  special characters are converted to %XX sequences.  */

OSErr EncodeTextAsURLTextToBuffer(unsigned char* buffer, long length, TextOutputBuffer *theBuffer);

    /* EncodeTextAsURLTextToString is a convenience routine that calls EncodeTextAsURLTextToBuffer.

    The only difference is that this routine packages up the resulting data in a LongTextString.

    Call DisposeLongTextString to release that memory when you are done using the resulting string. */

LongTextStringPtr EncodeTextAsURLTextToString(unsigned char* buffer, long length);

    /* DecodeURLTextAsTextToBuffer decodes a string from a URL into a regular string.  specifically,

    all %XX sequences are replaced with the appropriate characters. */

OSErr DecodeURLTextAsTextToBuffer(unsigned char* buffer, long length, TextOutputBuffer *theBuffer);

    /* DecodeURLTextAsTextToString is a convenience routine that calls DecodeURLTextAsTextToBuffer.

    The only difference is that this routine packages up the resulting data in a LongTextString.

    Call DisposeLongTextString to release that memory when you are done using the resulting string. */

LongTextStringPtr DecodeURLTextAsTextToString(unsigned char* buffer, long length);

#endif