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!
---