Carbon


NSLHexEncodeText

Header: NSL.h Carbon status: Under Evaluation

Encodes a portion of a URL.

OSStatus NSLHexEncodeText (
    const char *rawText, 
    UInt16 rawTextLen, 
    char *newTextBuffer, 
    UInt16 *newTextBufferLen, 
    Boolean *textChanged
);
Parameter descriptions
rawText

On input, a pointer to a character array containing the portion of the URL that is to be encoded. For example, if the URL is

afp://17.221.40.66?NAME=Kevs/G3

the portion of the URL that may contain illegal characters is Kevs/G3. In this example, the forward slash (/) is an illegal character.

rawTextLen

On input, a value of type UInt16 containing the length in bytes of rawText.

newTextBuffer

On input, a pointer to a buffer. On output, the buffer contains the encoded text.

newTextBufferLen

On input, a pointer to an unsigned short. On output, newTextBufferLen contains the length of the encoded text pointed to by newTextBuffer.

textChanged

On input, a pointer to a Boolean value. On output, textChanged is TRUE if the encoded data is different from the original data and FALSE if the encoded data has not changed.

function result

A result code. A value of noErr indicates that NSLHexEncodeText returned successfully.

DISCUSSION

The NSLHexEncodeText function uses the US ASCII character code set to encode the portion of a URL that may contain illegal characters. Illegal characters are hexadecimal values in ranging from 01 to 1F, from 80 to FF, and 7F, as well as the following characters:

< > " # { } | \ ^ ~ [ ]

In addition, NSLHexEncodeText also encodes the following characters that are reserved for URL syntax:

; / ? : @ = % &

Call NSLHexDecodeText NSLHexDecodeText to decode a string that has been encoded.

The NSLStandardRegisterURL function returns an error if the URL that you try to register contains illegal characters.

If NSLHexEncodeText returns noErr and textChanged is FALSE, newTextBuffer points to a copy of the data pointed to by rawText. That is, the data pointed to by rawText is copied regardless of whether any encoding takes place.


© 2000 Apple Computer, Inc. (Last Updated 7/13/2000)