newapi1

include/ncplugins.h

@@ -11,22 +11,24 @@ For internal use only.
 #ifndef NCPLUGINS_H
 #define NCPLUGINS_H
 
+/* Opaque */
+struct NCPluginList;
+
 #if defined(__cplusplus)
 extern "C" {
 #endif
 
 EXTERNL int NCZ_plugin_path_initialize(void);
 EXTERNL int NCZ_plugin_path_finalize(void);
 
-EXTERNL int NCZ_plugin_path_get(size_t* ndirsp, char** dirs);
-EXTERNL int NCZ_plugin_path_set(size_t ndirs, char** const dirs);
+EXTERNL int NCZ_plugin_path_get(struct NCPluginList* dirs);
+EXTERNL int NCZ_plugin_path_set(struct NCPluginList* dirs);
 
 EXTERNL int NC4_hdf5_plugin_path_initialize(void);
 EXTERNL int NC4_hdf5_plugin_path_finalize(void);
 
-EXTERNL int NC4_hdf5_plugin_path_get(size_t* ndirsp, char** dirs);
-EXTERNL int NC4_hdf5_plugin_path_set(size_t ndirs, char** const dirs);
-
+EXTERNL int NC4_hdf5_plugin_path_get(struct NCPluginList* dirs);
+EXTERNL int NC4_hdf5_plugin_path_set(struct NCPluginList* dirs);
 
 #if defined(__cplusplus)
 }

include/netcdf_aux.h

@@ -99,6 +99,9 @@ EXTERNL int ncaux_add_field(void* tag,  const char *name, nc_type field_type,
 /**************************************************/
 /* Path-list Utilities */
 
+/* Opaque */
+struct NCPluginList;
+
 /**
 Parse a string into a sequence of path directories.
 
@@ -110,17 +113,17 @@ The pathlist argument has the following syntax:
 
 @param pathlist a string encoding a list of directories
 @param sep  one of ';' | ':' | '\0' where '\0' means use the platform's default separator.
-@param ndirsp return the number of directories in dirsp
-@param dirsp return a vector of strings representing the directories parsed from pathlist; caller frees
-@return ::NC_NOERR
+@param dirs a pointer to an  NCPluginPath object for returning the number and vector of directories from the parse.
+@return ::NC_NOERR | NC_EXXX
 
-Note that this function is called twice: first time to get the number of directories
-and second to get the directories.
+Note: If dirs->dirs is not NULL, then this function
+will allocate the space for the vector of directory path.
+The user is then responsible for free'ing that vector
+(or call ncaux_plugin_path_reclaim).
 
 Author: Dennis Heimbigner
 */
-
-EXTERNL int ncaux_plugin_path_parse(const char* pathlist, char sep, size_t* ndirsp, char** dirs);
+EXTERNL int ncaux_plugin_path_parse(const char* pathlist, char sep, struct NCPluginList* dirs);
 
 /**
 Concatenate a vector of directories with the separator between.
@@ -132,37 +135,65 @@ The resulting string has following syntax:
     separator := ';' | ':'
     dir := <OS specific directory path>
     
-@param ndirs the number of directories
-@param dirsp the directory vector to concatenate
+@param dirs a pointer to an  NCPluginList object giving the number and vector of directories to concatenate.
 @param sep one of ';', ':', or '\0'
 @param catlen length of the cat arg including a nul terminator
 @param cat user provided space for holding the concatenation; nul termination guaranteed if catlen > 0.
 @return ::NC_NOERR
 @return ::NC_EINVAL for illegal arguments
 
-Note that this function is called twice: first time to get the expected size of
-the concatenated string and second to get the contents of the concatenation.
+Note: If dirs->dirs is not NULL, then this function
+will allocate the space for the vector of directory path.
+The user is then responsible for free'ing that vector
+(or call ncaux_plugin_path_reclaim).
 
 Author: Dennis Heimbigner
 */
+EXTERNL int ncaux_plugin_path_tostring(const struct NCPluginList* dirs, char sep, char** catp);
 
-EXTERNL int ncaux_plugin_path_tostring(size_t ndirs, char** const dirs, char sep, size_t* catlen, char* cat);
+/*
+Clear the contents of a NCPluginList object.
+@param dirs a pointer to an NCPluginList object giving the number and vector of directories to reclaim
+@return ::NC_NOERR
+@return ::NC_EINVAL for illegal arguments
 
+Author: Dennis Heimbigner
+*/
+EXTERNL int ncaux_plugin_path_clear(struct NCPluginList* dirs);
 
 /*
-Reclaim a char** object possibly produced by ncaux_plugin_parse function.
+Reclaim a NCPluginList object possibly produced by ncaux_plugin_parse function.
+WARNING: do not call with a static or stack allocated object.
+@param dirs a pointer to an  NCPluginList object giving the number and vector of directories to reclaim
+@return ::NC_NOERR
+@return ::NC_EINVAL for illegal arguments
 
-@param veclen the number of entries in vec
-@param vec    a char** vectore
+Author: Dennis Heimbigner
+*/
+EXTERNL int ncaux_plugin_path_reclaim(struct NCPluginList* dirs);
+
+/*
+Modify a plugin path set to append a new directory to the end.
+@param dirs a pointer to an  NCPluginList object giving the number and vector of directories to which 'dir' argument is appended.
 @return ::NC_NOERR
 @return ::NC_EINVAL for illegal arguments
+
+Author: Dennis Heimbigner
 */
+EXTERNL int ncaux_plugin_path_append(struct NCPluginList* dirs, const char* dir);
 
-EXTERNL int ncaux_plugin_path_freestringvec(size_t veclen, char** vec);
+/*
+Modify a plugin path set to prepend a new directory to the front.
+@param dirs a pointer to an  NCPluginList object giving the number and vector of directories to which 'dir' argument is appended.
+@return ::NC_NOERR
+@return ::NC_EINVAL for illegal arguments
+
+Author: Dennis Heimbigner
+*/
+EXTERNL int ncaux_plugin_path_prepend(struct NCPluginList* dirs, const char* dir);
 
 #if defined(__cplusplus)
 }
 #endif
 
 #endif /*NCAUX_H*/
-

include/netcdf_filter.h

@@ -113,39 +113,51 @@ EXTERNL int nc_inq_var_blosc(int ncid, int varid, int* hasfilterp, unsigned* sub
 /* Filter path query/set */
 EXTERNL int nc_filter_path_query(int id);
 
+#if defined(__cplusplus)
+}
+#endif
+
 /**************************************************/
 /* API for libdispatch/dplugin.c */
 
+/* Combine the vector of directory path plus it's length in a single struct. */
+typedef struct NCPluginList {
+    size_t ndirs; /* |dirs| */
+    char** dirs;
+} NCPluginList;
+
 /* Externally visible plugin path functions */
+#if defined(__cplusplus)
+extern "C" {
+#endif
 
 /**
- * Return the current sequence of directories in the internal plugin path list.
- * Since this function does not modify the plugin path, it can be called at any time.
- * @param ndirsp return the number of dirs in the internal path list
- * @param dirs memory for storing the sequence of directies in the internal path list.
- * @return NC_NOERR
+ * Return the current sequence of directories in the internal global
+ * plugin path list. Since this function does not modify the plugin path,
+ * it can be called at any time.
+ * @param dirs pointer to an NCPluginList object
+ * @return NC_NOERR | NC_EXXX
  * @author Dennis Heimbigner
  *
- * As a rule, this function needs to be called twice.
- * The first time with npaths not NULL and pathlist set to NULL
- *     to get the size of the path list.
- * The second time with pathlist not NULL to get the actual sequence of paths.
+ * WARNING: if dirs->dirs is NULL, then space for the directory
+ * vector will be allocated. If not NULL, then the specified space will
+ * be overwritten with the vector.
+ *
+ * Author: Dennis Heimbigner
 */
-
-EXTERNL int nc_plugin_path_get(size_t* ndirsp, char** dirs);
+EXTERNL int nc_plugin_path_get(NCPluginList* dirs);
 
 /**
  * Empty the current internal path sequence
  * and replace with the sequence of directories argument.
  *
  * Using a paths argument of NULL or npaths argument of 0 will clear the set of plugin paths.
- * @param ndirs length of the dirs argument
- * @param dirs to overwrite the current internal path list
- * @return NC_NOERR
+ * @param dirs pointer to an NCPluginList object containing
+ *        the number and vector of directory paths
+ * @return NC_NOERR | NC_EXXX
  * @author Dennis Heimbigner
 */
-
-EXTERNL int nc_plugin_path_set(size_t ndirs, char** const dirs);
+EXTERNL int nc_plugin_path_set(NCPluginList* dirs);
 
 #if defined(__cplusplus)
 }