Github user phrocker commented on a diff in the pull request:
https://github.com/apache/nifi-minifi-cpp/pull/448#discussion_r239477181
--- Diff: nanofi/include/api/nanofi.h ---
@@ -71,62 +94,173 @@ typedef int c2_start_callback(char *);
void enable_async_c2(nifi_instance *, C2_Server *, c2_stop_callback *,
c2_start_callback *, c2_update_callback *);
+/**
+ * Creates a new, empty flow
+ * @param instance the instance new flow will belong to
+ * @return a pointer to the created flow
+ **/
+flow *create_new_flow(nifi_instance * instance);
-uint8_t run_processor(const processor *processor);
-
-flow *create_new_flow(nifi_instance *);
-flow *create_flow(nifi_instance *, const char *);
+/**
+ * Creates new flow and adds the first processor in case a valid name is
provided
+ * @deprecated as there is no proper indication of processor adding
errors,
+ * usage of "create_new_flow" and "add_processor is recommended instead
+ * @param instance the instance new flow will belong to
+ * @param first_processor name of the first processor to be instanciated
+ * @attention in case first processor is empty or doesn't name any
existing processor, an empty flow is returned.
+ * @return a pointer to the created flow
+ **/
+DEPRECATED flow *create_flow(nifi_instance * instance, const char *
first_processor);
-flow *create_getfile(nifi_instance *instance, flow *parent, GetFileConfig
*c);
+/**
+ * Add a getfile processor to "parent" flow.
+ * Creates new flow in instance in case "parent" is nullptr
+ * @deprecated as getfile processor can be added using "add_processor"
function,
+ * properties can be set using "set_property".
+ * @param instance the instance the flow belongs to
+ * @param parent the flow to be extended with a new getfile processor
+ * @param c configuration of the new processor
+ * @return parent in case it wasn't null, otherwise a pointer to a new flow
+ */
+DEPRECATED flow *create_getfile(nifi_instance *instance, flow *parent,
GetFileConfig *c);
-processor *add_processor(flow *, const char *);
+/**
+ * Extend a flow with a new processor
+ * @param flow the flow to be extended with the new processor
+ * @param name name of the new processor
+ * @return pointer to the new processor or nullptr in case it cannot be
instantiated (wrong name?)
+ */
+processor *add_processor(flow * flow, const char * name);
processor *add_python_processor(flow *, void
(*ontrigger_callback)(processor_session *session));
-standalone_processor *create_processor(const char *);
+/**
+ * Create a standalone instance of the given processor.
+ * Standalone instances can be invoked without having an instance/flow
that contains them.
+ * @param name the name of the processor to instanciate
+ * @return pointer to the new processor or nullptr in case it cannot be
instantiated (wrong name?)
+ **/
+standalone_processor *create_processor(const char * name);
-void free_standalone_processor(standalone_processor*);
+/**
+ * Free a standalone processor
+ * @param processor the processor to be freed
+ */
+void free_standalone_processor(standalone_processor* processor);
/**
-* Register your callback to received flow files that the flow failed to
process
-* The flow file ownership is transferred to the caller!
-* The first callback should be registered before the flow is used. Can be
changed later during runtime.
-*/
+ * Register your callback to received flow files that the flow failed to
process
+ * The flow file ownership is transferred to the caller!
+ * The first callback should be registered before the flow is used. Can be
changed later during runtime.
+ * @param flow flow the callback belongs to
+ * @param onerror_callback callback to execute in case of failure
+ * @return 0 in case of success, -1 otherwise (flow is already in use)
+ **/
int add_failure_callback(flow *flow, void
(*onerror_callback)(flow_file_record*));
-
/**
-* Set failure strategy. Please use the enum defined in cstructs.h
-* Return values: 0 (success), -1 (strategy cannot be set - no failure
callback added?)
-* Can be changed runtime.
-* The default strategy is AS IS.
-*/
+ * Set failure strategy. Please use the enum defined in cstructs.h
+ * Can be changed runtime.
+ * The default strategy is AS IS.
+ * @param flow the flow to set strategy for
+ * @param strategy the strategy to be set
+ * @return 0 (success), -1 (strategy cannot be set - no failure callback
added?)
+ **/
int set_failure_strategy(flow *flow, FailureStrategy strategy);
-int set_property(processor *, const char *, const char *);
+/**
+ * Set property for a processor
+ * @param processor the processor the property is set for
+ * @param name name of the property
+ * @param value value of the property
+ * @return 0 in case of success, -1 otherwise (the processor doesn't
support such property)
+ **/
+int set_property(processor * processor, const char * name, const char *
value);
-int set_standalone_property(standalone_processor*, const char*, const char
*);
+/**
+ * Set property for a standalone processor
+ * @param processor the processor the property is set for
+ * @param name name of the property
+ * @param value value of the property
+ * @return 0 in case of success, -1 otherwise (the processor doesn't
support such property)
+ **/
+int set_standalone_property(standalone_processor * processor, const char *
name, const char * value);
-int set_instance_property(nifi_instance *instance, const char*, const char
*);
+/**
+ * Set property for an instance
+ * @param instance the instance the property is set for
+ * @param name name of the property
+ * @param value value of the property
+ * @return 0 in case of success, -1 otherwise. Always succeeds unless
instance or name is nullptr/emtpy.
+ **/
+int set_instance_property(nifi_instance *instance, const char * name,
const char * value);
-char * get_property(const processor_context * context, const char * name);
+/**
+ * Get a property. Should be used in custom processor logic callbacks.
+ * @attention The returned value transfers ownership, it's the callers
responsibility to free it!
+ * @param context the current processor context
+ * @param name name of the property
+ * @return null-terminated char* in case of success, nullptr otherwise
+ **/
+char * get_property(const processor_context * context, const char * name);
-int free_flow(flow *);
+/**
+ * Free a flow
+ * @param flow the flow to free
+ * @attention All the processor in the flow are freed, too! Actions
performed on freed processors are undefined!
+ * @return 0 in case of success, -1 otherwise. Always succeeds unless flow
is nullptr.
+ **/
+int free_flow(flow * flow);
+/**
+ * Get the next flow file of the given flow
+ * @param instance the instance the flow belongs to
+ * @param flow the flow to get flowfile from
+ * @return a flow file record or nullptr in case no flowfile was generated
by the flow
+ **/
flow_file_record *get_next_flow_file(nifi_instance *, flow *);
-size_t get_flow_files(nifi_instance *, flow *, flow_file_record **,
size_t);
+/**
+ * Get all flow files of the given flow
+ * @param instance the instance the flow belongs to
+ * @param flow the flow to get flowfiles from
+ * @param flowfiles target area to copy the flowfiles to
+ * @param size the maximum number of flowfiles to copy to target (size of
target)
+ * @return the number of flow files copies to target. Less or equal to
size.
+ **/
+size_t get_flow_files(nifi_instance * instance, flow * flow,
flow_file_record ** flowfiles, size_t size);
flow_file_record *get(nifi_instance *,flow *, processor_session *);
--- End diff --
The nomenclature that's common in NiFi is get, so we should work toward
keeping some commonality, but get(...) can be changed to use the structs you've
defined as it's new within this release and there are no guarantees. I'll
create a follow on ticket (MINIFICPP-692). At the very least the consistency
should exist be the language python, ruby, or C in how funcitons get accessed
for obtaining the flowfile. Naming is secondary to that need.
---
