Returned Handles

Many API functions take a pointer to an integer indicating the size of a returned list of object handles. For example, saf_find_files has int ``num_files`` and ``SAF__File`` **files arguments. Many of SAF_’s other find functions have an analogous pair of args; one for the *number of returned items and the other for the list of returned items. In the text below, we refer to these, generically, as the number and list arguments.

The memory for the returned handles can be allocated by the client or by the lib. Furthermore, the client can determine the size of the returned list by first calling the function with a non-NULL number argument and the list argument set to NULL. For example, to determine the number of supplemental files whose names begin with “gorfo”…

 int count;
 saf_find_files(db, "gorfo*", &count, NULL);

will return in COUNT, the number of matching supplemental files.

If the client allocates the memory for the returned handles, the number argument is used both as an input and as an output argument. On input, the number argument is expected to point to a value indicating the number of items that can be stored in the list argument and the list argument is expected to point to the memory for the returned handles allocated by the client. For example…

 int count = 5;
 SAF_Files files[5]; *pfiles = &files[0];
 saf_find_files(db, "gorfo*", &count, &pfiles);

Furthermore, if SAF attempts to return more items into this memory than the size indicated by the client via the number argument, the function will return an error.

If the client wants the library to allocate the memory for the returned list of handles, the client is expected to pass a value for the list argument that points to NULL. For example…

 int count = 0;
 SAF_Files *files = NULL;
 saf_find_files(db, "gorfo*", &count, &pfiles);