Q: I'm writing a Unicode-based Mac OS X application. When I rename a file (using FSRenameUnicode), is it OK to pass 0 to the textEncodingHint parameter?
A: In general, no. When using the Unicode-based File Manager APIs, you must either supply a valid text encoding hint or specifically indicate that there is no text encoding hint by passing kTextEncodingUnknown. In most cases a Unicode-based application does not have a text encoding hint handy, and thus should pass kTextEncodingUnknown and not 0.
The value 0 is equivalent to kTextEncodingMacRoman, which implies that you believe the name is composed of Roman characters. If your application supports Unicode throughout, you have no idea whether the characters are Roman or not, and thus you're lying about the text encoding hint. It's never good to lie to the File Manager! The incorrect text encoding hint will probably not affect Unicode-based applications, like the Mac OS X Finder, but it may end up confusing non-Unicode applications, for example applications running inside the Classic compatibility environment.
Here are some simple rules for dealing with File Manager text encoding hints in a Unicode-based application.
- When supplying a text encoding hint to the File Manager (for example, to the
textEncodingHint parameter of FSMakeFSRefUnicode and FSRenameUnicode), use kTextEncodingUnknown.
- When getting information about a File Manager object, it's best not to ask for the text encoding hint (make sure that
kFSCatInfoTextEncoding is clear in the whichInfo parameter to FSGetCatalogInfo).
- A key exception to the above rules is that, when copying a File Manager object, you should always copy the text encoding hint. For an example of how to copy a File Manager object, see the FSCopyObject sample code.
The rules for non-Unicode applications are more complex, and our suggestion is that it is better to spend your time adopting Unicode than worrying about this case.
On a related topic, if you're creating a Unicode-based external file system (a VFS KEXT), you can choose whether to store the text encoding hint in your file system. However, if you don't store the text encoding hint, you should be sure to return kTextEncodingMacUnicode as the value of the ATTR_CMN_SCRIPT attribute in your VOP_GETATTRLIST entry point. Failure to do this will cause Japanese file names to show up correctly in Carbon applications but incorrectly in applications running inside the Classic compatibility environment.
[Jan 20 2003]
|