On Tue, June 24, 2008 1:04 am, Andreas Schulz wrote:
> So, maybe we can agree on the following interface:
That should work. Just a few mostly small comments:
In the delete_* functions, I'd use a more descriptive name for the
parameter than "garbage", e.g.:
void delete_key_names(char **key_names);
In the description for get_key_names:
> * Memory allocated for the strings must be freed by the caller
> * via destroy_key_names() when not needed any longer, i.e.
> * after all codes have been posted via post_new_code.
I would avoid specifically mentioning deleting the memory after
post_new_code, because some clients will probably do this:
char ** key_names = get_key_names(...);
duplicate key_names into some internal structure (e.g. Python strings in a
list)
delete_key_names(key_names);
process the internal structure
The internal structure could be created by duplicating all the strings and
indexing them in some different way. Note: The key names are obviously
required to call post_new_code later, but there's no requirement it be the
same actual string (memory location holding it, that is), but simply that
the content of the string must be the same.
So, perhaps simply say this instead:
> * Memory allocated for the strings must be freed by the caller
> * via destroy_key_names() when no longer needed.
Same for other "allocating" functions.
In get_key_names, rather than returning an array with a NULL entry to
indicate the end, how about this:
int get_key_names(uint8_t *data, uint32_t size,
char *** key_names, uint32_t *key_names_length);
and called/used like this:
char **key_names;
uint32_t key_names_length;
int err = get_key_names(d, s, &key_names, &key_names_length);
if (err != SUCCESS) {
// handle error here
return;
}
for (int i = 0; i < key_names_length; ++i) {
printf("Key name %d is '%s'\n", i, key_names[i]);
}
This:
a) Can allow more meaningful error status
b) Is explicit about the array length up front
One could make a similar change to encode_for_posting, but since that's
always returning just one string, I'm not worried about that so much; your
call.
I would rename post_new_code's "code" parameter to "encoded", to hint that
it comes from encode_for_posting.
Thanks for implementing this guys, and being open to API changes.
-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
_______________________________________________
concordance-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/concordance-devel
