> >I would suggest we begin the api with the simple types (say, strings
> >and doubles) before trying to tackle the more complex or
> >implementation-specific ones like arrays and colors.
>
> Coward. <g> ;-)
Gee, thanks for the vote of support, Uli ! ;-)
> >char* ParamCStringValue( XParamRef param );
> >char* ParamCharArrayValue( XParamRef param, unsigned long
*ioLength );
> >double ParamDoubleValue( XParamRef param );
> >void CopyParamCStringValue( XParamRef param, char** outStrPtr,
> > unsigned long *lengthPtr );
> >void CopyParamCharArrayValue( XParamRef param, char** outStrPtr,
> > unsigned long * lengthPtr );
>
> Since we also have the "copy" calls, I don't mind the ones above.
However,
> I think the char** is wrong. I wouldn't want to have the "copy" calls
> allocating the memory for me. Instead I'd want to be able to pass in a
> pre-allocated block to have the data copied to. This is especially
useful
> on the Mac, where you have at least four kinds of memory: new,
malloc(),
> NewPtr() and NewHandle(). Could we maybe change the copy calls to:
>
> unsigned long GetParamSize( XParamRef param );
> void CopyParamCStringValue( XParamRef param, char* outData );
> void CopyParamCharArrayValue( XParamRef param, char*
outData );
>
> The CopyXXX calls would take a pointer you allocated and fill it
with the
> data. Of course, the caller would have to make sure the buffer is large
> enough, using GetParamSize().
This sounds fine. Having GetParamSize() is a good idea in any case,
since we want to support non-null-terminated strings. Using this
approach, the external author has a choice. They can call
ParamCStringValue(), for example, to get a pointer to memory owned
and managed by the xTalk host, or they can call
CopyParamCStringValue() to get their own copy to do with as they
wish.
They could, of course, just call ParamCStringValue() and then copy
the memory it points to, which would seem to eliminate the need for
the Copy... functions altogether. The reason I included the Copy...
functions in the first place was to save double-copying in some
cases. For example, if the host is holding a Unicode string and the
external requests a C string using ParamCStringValue(), the host will
have to convert to a C string internally and return a pointer to
that string which the external would then copy. If
CopyParamCStringValue() were called instead, the host would have the
opportunity to convert the Unicode string directly into the
external's buffer. I don't know if it's really worth the extra
complexity, though, for the possible gain in performance in a limited
number of cases. Unless you're dealing with megabyte-size strings,
the performance gain is probably insignificant, so maybe we should
just eliminate the Copy... functions.
> [snip] It is not practiceable to have the XCMD
> dispose of memory it received from the host in a cross-platform
way, as the
> only calls that would work this way are DisposePtr() and
DisposeHandle(),
> which are inherently Mac-specific. Let the caller create the
memory for the
> CopyXXX() calls and the problem is solved.
Okay, that's good to keep in mind, although in this case eliminating
the Copy... calls would also solve the problem. ;-)
> One more thing: I think CharArray is not a good choice of words
either. It
> can be mixed up too easily with associative arrays and since supporting
> those is also a long-term goal, we should make sure to avoid
terminology
> clashes right away. Maybe "Buffer" or "CharBuffer" or "TextBuffer" ?
Maybe. The term "array", however, has been used consistently in
programming for many years to refer to a numerically-indexed sequence
of values. Using it to refer to "associative arrays" is, IMHO, a
bad idea. Associative arrays are very different beasts which would
be better to refer to as HashTables or Dictionaries.
Getting back to the case at hand, what is the purpose of the
ParamCharArrayValue() call above, anyway? If its purpose is to
provide access to arbitrary binary data, then maybe "byte" or "data"
would be an appropriate term. How about changing it to
ParamDataValue(), which returns a pointer to an array of bytes:
void * ParamDataValue( XParamRef param, unsigned long *ioLength );
I nearly eliminated the ioLength parameter since we now have
GetParamSize(), but it's not clear that they would return the same
value -- should GetParamSize() return the raw size in bytes, or the
number of characters in a string? In the case of Unicode they will
be very different numbers. Always more questions...
Cheers,
Doug
