Github user arpadboda commented on a diff in the pull request:
https://github.com/apache/nifi-minifi-cpp/pull/448#discussion_r239116973
--- Diff: nanofi/include/api/nanofi.h ---
@@ -68,60 +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 defailt 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);
-int free_flow(flow *);
+/**
+ * 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);
+/**
+ * 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 *);
+/**
+ * Invoke a standalone processor without input data.
+ * The processor is expected to generate flow file.
+ * @return a flow file record or nullptr in case no flowfile was generated
+ **/
flow_file_record *invoke(standalone_processor* proc);
+/**
+ * Invoke a standalone processor with input flow file
+ * @param input_ff input flow file, which can belong be the output of
another processor or flow
+ * @return a flow file record or nullptr in case no flowfile was generated
+ **/
flow_file_record *invoke_ff(standalone_processor* proc, const
flow_file_record *input_ff);
+/**
+ * Invoke a standalone processor with file input
+ * @param path specifies the file system path of the input file
+ * @return a flow file record or nullptr in case no flowfile was generated
+ **/
flow_file_record *invoke_file(standalone_processor* proc, const char*
path);
-flow_file_record *invoke_chunck(standalone_processor* proc, uint8_t* buf,
uint64_t);
+/**
+ * Invoke a standalone processor with some in-memory data
+ * @param buf specifies the beginning of the input buffer
+ * @param size specifies the size of the buffer
+ * @return a flow file record or nullptr in case no flowfile was generated
+ **/
+flow_file_record *invoke_chunck(standalone_processor* proc, uint8_t* buf,
uint64_t size);
--- End diff --
Good spot, fixed!
---
