![]() |
CFStringGetBytes | Header: CFString.h |
Fetches a range of the characters represented by a CFString object into a byte buffer after converting the characters to a specified encoding. This function enables lossy conversion and handles any external represenation of the characters.
CFIndex CFStringGetBytes ( CFStringRef theString, CFRange range, CFStringEncoding encoding, UInt8 lossByte, Boolean isExternalRepresentation, UInt8 *buffer, CFIndex maxBufLen, CFIndex *usedBufLen );
Pass a reference to a CFString object that you want to convert to a string of a certain 8-bit encoding.
Pass a structure of type CFRange that indicates the range of characters in theString to process.
Pass a constant of type CFStringEncoding that specifies the encoding of the characters to be copied to the byte buffer.
Pass the character (for example, '?') that should be substituted for characters that cannot be converted to the specified encoding. Pass zero if you do not want lossy conversion to occur.
Pass TRUE if you want the result to be in an "external representation" format. In such a format, they may include a byte order marker (BOM) specifying endianness and the function might have to perform byte swapping.
Pass a pointer to a byte buffer of at least size maxBufLen. The buffer can be allocated on the heap or stack. Pass NULL if you do not want conversion to take place but instead want to know if conversion will succeed (the function result is greater than zero) and, if so, how many bytes are required (usedBufLen).
Pass an integer specifying the maximum size of the buffer to which converted characters are written.
Pass the address of a variable of type CFIndex. On return, the function will write to this variable the number of converted bytes actually in the byte buffer. You may pass NULL if you are not interested in this information.
An integer specifying the number of characters converted.
The CFStringGetBytes function is the basic encoding-conversion function of String Services. As with the other functions that get the character contents of CFString objects, is allows conversion of those characters to a supported 8-bit encoding. Unlike most of those other functions, it also allows "lossy conversion." The function permits the specification of a "loss byte" in a parameter; if a character cannot be converted this character is substituted and conversion proceeds. (With the other functions, conversion stops at the first error and the operation fails.)
Because this function takes a range and returns the number of characters converted, it can be called repeatedly with a small fixed size buffer and different ranges of the string to do the conversion incrementally.
The CFStringGetBytes function also handles any necessary manipulation of character data in an "external representation" format. This format makes the data portable and persistent (disk-writable); in Unicode it often includes a BOM (byte order marker) that specifies the endianness of the data.
The CFStringCreateExternalRepresentation function also handles external representations and performs lossy conversions. The complementary function CFStringCreateWithBytes creates a CFString object from the characters in a byte buffer.