>>For SelectOneTime, the docs say "Implemented only if 3.1 New Feature Set is >>present." which gives me a clue that I can't use this function with pre-3.1 >>systems. However, in other cases, such as SerReceive, there is nothing that >>tells me that this function does not exist prior to PalmOS 2.0. > >That's precisely why we added the Compatibility appendix. You're right, it >doesn't talk about SerReceive; that seems to be a bug in the docs. But >there are plenty of other functions listed in there... I presume that's >what you want, though with SerReceive added? No. I'd like something in SerReceive that warns me I can't use it with 1.x. When I'm writing code and I look up a function, it should be clear if I can't use it due to the version of the operating system it requires. Metrowerks does this very nicely in documents like the MSL C Reference. There is a little box above each function which indicates each OS that supports the function. >We beat this topic to death in a thread here a while back. The reasoning >from the folks who originally used this convention was that the initial >versions of the APIs would go away in the future, and so when people >upgraded their SDK they should use the new form. It's a lot easier to deprecate functions if you keep the names the same. All you have to do is #ifdef them out of the headers with an OS version flag to make them become invalid. By re-using old names with new functions you make it harder to update old code. Just to do a simple re-compile with no functional change can require making hundreds of edits. Furthermore, the compiler only flags these cases due to type mismatches and parameter count errors. In the worst case (which I don't think has happened yet), the new definition might have the same number of parameters with the same types, but the meanings could be different. In this case, you won't even get a compiler error - just bad code. I have never seen any other OS API which handles new function definitions this way. There's a reason for that. Bill Goodman Cyclos
