ori.h

 * @brief Delete an ORI context.
 *
 * This function disconnects from the remote host (if connected), destroys the ORI threads and releases all associated ORI resources.
 *
 * @param ori The ORI context to delete.
 * @return Void.
 */
void ORI_Free(ORI_s * ori);

/**
 * @brief Enable ORI debug outputs.
 *
 * This function enables the ORI debug prints to stdout.
 *
 * @param ori The ORI context.
 * @return Void.
 */
void ORI_EnableDebug(ORI_s * ori);

/**
 * @brief Disable ORI debug outputs.
 *
 * This function disables the ORI debug prints to stdout.
 *
 * @param ori The ORI context.
 * @return Void.
 */
void ORI_DisableDebug(ORI_s * ori);

/**
 * @brief Connect to an ORI remote host (RE).
 *
 * This functions tries to connect the ORI context to a RE for C&M. The IP address @p serverIP of the RE and the network port @p port
 * indicates with which host form the TCP link. The @p timeout_ms specifies the timeout (in milliseconds) of the connection attempt. <br>
 * Once connected, callbacks from the ORI context may be called at any time, and the TCP Link monitoring timer shall be started on both RE and REC side. <br>
 * The REC side TCP link monitoring timer is integrated in the ORI library and is managed by the ORI_HealthCheck() function.
 *
 * @param ori The ORI context.
 * @param serverIP The IP address of the RE in string format (e.g. "192.168.100.1").
 * @param port The port to use for TCP connection.
 * @param timeout_ms The timeout in milliseconds of the connection attempt.
 * @param retry_timer_s Request retry timer in seconds when no response has been received from RE, until TCP link times-out, 0 means no retries will happen.
 * @return The result of the connection, ::ORI_Result_SUCCESS is returned if the connection is established.
 */
ORI_Result_e ORI_Connect(ORI_s * ori, const char * serverIP, int port, unsigned int timeout_ms, uint16_t retry_timer_s);

/**
 * @brief Disconnect from an ORI remote host (RE).
 *
 * This function disconnects the ORI context from the RE. This function does nothing if not currently connected. <br>
 * At disconnection, all buffered ORI response and indication messages are discarded, if any are still waiting to be processed.
 *
 * @param ori The ORI context.
 * @return Void.
 */
void ORI_Disconnect(ORI_s * ori);

/**
 * @brief Retrieve which Ethernet interface is used by the ORI TCP link.
 *
 * Returns the name of the currently (or last before disconnection) Ethernet interface used by the ORI TCP Link.
 *
 * @param ori The ORI context.
 * @return Name of the Ethernet interface (e.g. "eth2").
 */
const char * ORI_InterfaceName(ORI_s * ori);


/*-----------------------------------------------------------------------------------------
 * DEVICE MANAGEMENT
 *-----------------------------------------------------------------------------------------*/

/**
 * @brief Perform a RE Health Check procedure.
 *
 * This function performs the Health Check procedure with the RE to verify that the OCP layer is functioning correctly. <br>
 * A successful health check will update and re-start the TCP link timeout using the new @p tcpLinkMonTimeout parameter
 * of the RE and the ORI library (REC side). <br>
 * It is the application's responsibility to re-call this function within the specified Health Check Idle Timer which should
 * be at least 5 seconds lower than the timeout value of @p tcpLinkMonTimeout.
 *
 * @param ori The ORI context.
 * @param tcpLinkMonTimeout The new TCP Link Monitoring timeout value in seconds to store in the RE. Minimum value: 30 except special value 0 which means no timeout.
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_HealthCheck(ORI_s * ori, uint16_t tcpLinkMonTimeout, ORI_Result_e * RE_result);

/**
 * @brief Perform a RE Set Time procedure.
 *
 * This function performs the Set Time procedure with the RE to set the absolute time reference used by the RE. <br>
 * The time reference is obtained from the calling application's local time reference.
 *
 * @param ori The ORI context.
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_SetTime(ORI_s * ori, ORI_Result_e * RE_result);

/**
 * @brief Perform a RE Reset procedure.
 *
 * This function performs the Reset procedure with the RE. <br>
 * If successful, the RE shall close the TCP Link and reset itself.
 *
 * @param ori The ORI context.
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_Reset(ORI_s * ori, ORI_Result_e * RE_result);



/*-----------------------------------------------------------------------------------------
 * SOFTWARE MANAGEMENT
 *-----------------------------------------------------------------------------------------*/

/**
 * @brief Perform a RE Version Query procedure.
 *
 * This function performs the Version Query procedure with the RE. <br>
 * If successful, the @p REVersion structure shall be filled with all the vendor specific RE version information,
 * containing the product information, hardware version and software images stored in the RE.
 *
 * @param ori The ORI context.
 * @param REVersion The RE version information structure.
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_VersionQuery(ORI_s * ori, ORI_REVersion_s * REVersion, ORI_Result_e * RE_result);


/**
 * @brief Perform a RE Software Update Preparation procedure.
 *
 * This function performs the Software Update Preparation procedure with the RE. <br>
 * If successful, the RE shall start downloading the specified Software Upgrade Package @p SwUpgradePkgVer file from the specified
 * FTP server using the login credentials @p ftpSrvIpAddress, @p ftpSrvUserName and @p ftpSrvPassword. <br>
 * The Software file format is RE vendor specific. <br>
 * After download, the RE will store this new software package in non-volatile memory as the passive image. <br>
 * On completion of the process, the RE shall send a message indicating file transfer completion. If a callback is specified in the ORI context,
 * the callback ::ORI_IndCallback_f will be called with the enum ::ORI_IndicationType_FileTransferComplete
 * passed as parameter, as well as the file transfer completion result (success, or failure, with additional information).
 *
 * @param ori The ORI context.
 * @param ftpSrvIpAddress The FTP server address as a decimal point notation (e.g. "192.168.1.1").
 * @param ftpSrvUserName The FTP server login used by the RE.
 * @param ftpSrvPassword The FTP server password used by the RE.
 * @param ftpSrvSwPkgDirPath The FTP server directory location of the software package file.
 * @param SwUpgradePkgVer The name of the software package file.
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_SoftwareUpdatePrep(ORI_s * ori, const char * ftpSrvIpAddress, const char * ftpSrvUserName, const char * ftpSrvPassword,
											const char * ftpSrvSwPkgDirPath, const char * SwUpgradePkgVer, ORI_Result_e * RE_result);

/**
 * @brief Perform a RE Software Activation procedure.
 *
 * This function performs the Software Activation procedure with the RE. <br>
 * If successful, the RE shall activate its passive software image, set its previous active image as passive, close the TCP Link then reset itself.
 *
 * @param ori The ORI context.
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_SoftwareActivation(ORI_s * ori, ORI_Result_e * RE_result);



/*-----------------------------------------------------------------------------------------
 * CONFIGURATION MANAGEMENT
 *-----------------------------------------------------------------------------------------*/

/**
 * @brief Perform a RE Object Parameter Reporting procedure.
 *
 * This function performs the Object Parameter Reporting procedure with the RE. <br>
 * The target object or set of objects is specified by the arguments @p object and @p wildcard: <br>
 * - @p object is not @c NULL and @p wildcard is 0 : the targeted object is @p object. <br>
 * - @p object is not @c NULL and @p wildcard is not 0 : the targeted objects are all the children of @p object. <br>
 * - @p object is @c NULL : the targeted objects are all the objects in the model. <br>
 *
 * The parameter to report is defined by @p param. If @p param is ::ORI_ObjectParam_All, then all the parameters of the targeted
 * object(s) shall be reported. <br>
 * On success, the parameters of the targeted objects are updated in the model. <br>
 * If the RE reported parameters for objects not present in the model image in the REC, the model is internally updated and
 * the new objects created (this will be the case at initial software alignment, as the ORI GS specifies
 * a Parameter Reporting "ALL objects" and "ALL parameters" shall be done at start-up).
 *
 * @param ori The ORI context.
 * @param object The target object, or parent object, or @c NULL if no specific object; depending on @p wildcard.
 * @param wildcard Wildcard for targeting all objects, or all children objects; depending on @p object being @c NULL.
 * @param param The parameter to report, or all if ::ORI_ObjectParam_All.
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_ObjectParamReport(ORI_s * ori, ORI_Object_s * object, int wildcard, ORI_ObjectParam_e param, ORI_Result_e * RE_result);

/**
 * @brief Perform a RE Object Parameter Modify procedure.
 *
 * This function performs the Object Parameter Modify procedure with the RE. <br>
 * The object for which the parameter(s) is(are) to be modified is given by @p object. <br>
 * The members of the @p params union for the specified target object type shall be set prior to calling this function, and each of the
 * parameter to modify must be specified in the @p paramList array. The number of parameters to set must be given by @p numParams. <br>
 * On procedure completion, the @p paramResult[] array will be filled with the results of each independent parameter modify attempt.
 *
 * @param ori The ORI context.
 * @param object The target object.
 * @param params The parameters union with values set for the parameters to modify.
 * @param paramList The array of enumerated parameters to modify. ::ORI_ObjectParam_All is not a valid enumeration for this procedure.
 * @param numParams The number of parameters to modify, must be > 0.
 * @param paramResult The return array for the individual result response for each parameter to modify.
 * @param RE_globalResult The RE response global result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_ObjectParamModify(ORI_s * ori, ORI_Object_s * object, ORI_ObjectParams_u params, ORI_ObjectParam_e paramList[],
										uint32_t numParams, ORI_Result_e paramResult[], ORI_Result_e * RE_globalResult);



/*-----------------------------------------------------------------------------------------
 * OBJECT LIFECYCLE
 *-----------------------------------------------------------------------------------------*/

/**
 * @brief Perform a RE Object Creation procedure.
 *
 * This function performs the Object Creation procedure with the RE. <br>
 * The object type to create is given by @p typeRef. <br>
 * The parameters @p params, @p paramList, @p numParams and @p paramResult function in the same maner as in the ORI_ObjectParamModify() procedure
 * and can be used to set default parameters for the newly created object. @p numParams can be set to 0, in which case no parameter is applied
 * to the new object. <br>
 * The created object is added in the model. <br>
 * This function also returns in @p newObject a reference in the model of the newly created object.
 *
 * @param ori The ORI context.
 * @param typeRef The type reference of the object to create.
 * @param params The parameters union with values set for the parameters to set.
 * @param paramList The array of enumerated parameters to set. ::ORI_ObjectParam_All is not a valid enumeration for this procedure.
 * @param numParams The number of parameters to set, can be 0.
 * @param paramResult The return array for the individual result response for each parameter to set.
 * @param newObject Reference to the newly created object.
 * @param RE_globalResult The RE response global result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_ObjectCreation(ORI_s * ori, ORI_ObjectTypeRef_s typeRef, ORI_ObjectParams_u params, ORI_ObjectParam_e paramList[],
										uint32_t numParams, ORI_Result_e paramResult[], ORI_Object_s ** newObject, ORI_Result_e * RE_globalResult);

/**
 * @brief Perform a RE Object Deletion procedure.
 *
 * This function performs the Object Deletion procedure with the RE. <br>
 * If successful, the object specified by @p object shall be deleted from the RE and removed from the library model.
 *
 * @param ori The ORI context.
 * @param object The object to delete.
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_ObjectDeletion(ORI_s * ori, ORI_Object_s * object, ORI_Result_e * RE_result);



/*-----------------------------------------------------------------------------------------
 * OBJECT STATE MANAGEMENT
 *-----------------------------------------------------------------------------------------*/

/**
 * @brief Perform a RE Object State Reporting procedure.
 *
 * This function performs the Object State Reporting procedure with the RE. <br>
 * The target object or set of objects is specified by the arguments @p object and @p wildcard: <br>
 * - @p object is not @c NULL and @p wildcard is 0 : the targeted object is @p object. <br>
 * - @p object is not @c NULL and @p wildcard is not 0 : the targeted objects are all the children of @p object. <br>
 * - @p object is @c NULL : the targeted objects are all the objects in the model. <br>
 *
 * The state type to report is defined by @p stateType. If @p stateType is ::ORI_StateType_All, then all the states of the targeted
 * object(s) shall be reported. <br>
 * On success, the states of the targeted objects are updated in the model. <br>
 * If the RE reported states for objects not present in the model image in the REC, the model is internally updated and
 * the new objects created (this will be the case at initial software alignment, as the ORI GS specifies a State
 * Reporting "ALL objects" and "ALL states" shall be done at start-up).
 * If @p eventDrivenReport is set to ::ORI_EventDrivenReport_True or ::ORI_EventDrivenReport_False the event driven state reporting of the object is enabled
 * or disabled. Pass ::ORI_EventDrivenReport_NoModify to keep the event driven state reporting as is.
 *
 * @param ori The ORI context.
 * @param object The target object, or parent object, or @c NULL if no specific object; depending on @p wildcard.
 * @param wildcard Wildcard for targeting all objects, or all children objects; depending on @p object being @c NULL.
 * @param stateType The parameter to report, or all if ::ORI_StateType_All.
 * @param eventDrivenReport Set event driven state reporting of the object if applicable.
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_ObjectStateReport(ORI_s * ori, ORI_Object_s * object, int wildcard, ORI_StateType_e stateType,
											ORI_EventDrivenReport_e eventDrivenReport, ORI_Result_e * RE_result);

/**
 * @brief Perform a RE Object State Modification procedure.
 *
 * This function performs the Object State Modification procedure with the RE. <br>
 * If successful, the administrative state (AST) of the target object will be set to @p ast.
 *
 * @param ori The ORI context.
 * @param object The object on which to set the state.
 * @param ast The administrative state to set.
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_ObjectStateModification(ORI_s * ori, ORI_Object_s * object, ORI_AST_e ast, ORI_Result_e * RE_result);



/*-----------------------------------------------------------------------------------------
 * FAULT MANAGEMENT
 *-----------------------------------------------------------------------------------------*/

/**
 * @brief Perform a RE Object Fault Reporting procedure.
 *
 * This function performs the Object Fault Reporting procedure with the RE. <br>
 * The target object or set of objects is specified by the arguments @p object and @p wildcard: <br>
 * - @p object is not @c NULL and @p wildcard is 0 : the targeted object is @p object. <br>
 * - @p object is not @c NULL and @p wildcard is not 0 : the targeted objects are all the children of @p object. <br>
 * - @p object is @c NULL : the targeted objects are all the objects in the model. <br>
 *
 * On success, the faults of the targeted objects are updated in the model. <br>
 * If the RE reported faults for objects not present in the model image in the REC, the model is internally updated and
 * the new objects created (this will be the case at initial software alignment, as the ORI GS specifies a Fault
 * Reporting "ALL objects" shall be done at start-up).
 * If @p eventDrivenReport is set to ::ORI_EventDrivenReport_True or ::ORI_EventDrivenReport_False the event driven fault reporting of the object is enabled
 * or disabled. Pass ::ORI_EventDrivenReport_NoModify to keep the event driven fault reporting as is.
 *
 * @param ori The ORI context.
 * @param object The target object, or parent object, or @c NULL if no specific object; depending on @p wildcard.
 * @param wildcard Wildcard for targeting all objects, or all children objects; depending on @p object being @c NULL.
 * @param eventDrivenReport Set event driven fault reporting of the object if applicable.
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_ObjectFaultReport(ORI_s * ori, ORI_Object_s * object, int wildcard, ORI_EventDrivenReport_e eventDrivenReport, ORI_Result_e * RE_result);


/*-----------------------------------------------------------------------------------------
 * LOGGING
 *-----------------------------------------------------------------------------------------*/

/**
 * @brief Perform a File Upload procedure.
 *
 * This function performs a File Upload procedure with the RE or with a Log Object. <br>
 * If successful, a File Upload should be initiated. <br>
 * On completion of the process, the RE shall send a message indicating file upload completion. If a callback is specified in the ORI context,
 * the callback ::ORI_IndCallback_f will be called with the enum ::ORI_IndicationType_UploadFileCmpl
 * passed as parameter, as well as the file upload completion result.
 *
 * @param ori The ORI context.
 * @param object The object targeted for the file upload. Must be a RE or Log object.
 * @param ftpSrvIpAddress The FTP server address as a decimal point notation (e.g. "192.168.1.1").
 * @param ftpSrvUserName The FTP server login used by the RE.
 * @param ftpSrvPassword The FTP server password used by the RE.
 * @param ftpSrvFilePath The FTP server path to the file to upload.
 * @param REFilePath The RE file path for a generic file upload. Used only in the case of a RE object.
 * @param maxUploadFileSize The maximum size in kBytes accepted for uploading the file. Pass 0 for no size limit.
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_FileUpload(ORI_s * ori, ORI_Object_s * object, const char * ftpSrvIpAddress, const char * ftpSrvUserName, const char * ftpSrvPassword,
										const char * ftpSrvFilePath, const char * REFilePath,  uint16_t maxUploadFileSize, ORI_Result_e * RE_result);


/*-----------------------------------------------------------------------------------------
 * AISG
 *-----------------------------------------------------------------------------------------*/

/**
 * @brief Perform an AISG Device Scan procedure.
 *
 * This function performs an AISG Scan Device procedure with an AISG Port Object. <br>
 * On completion of the process, the RE shall send a message indicating scan device completion.
 *
 * @param ori The ORI context.
 * @param object The object targeted for the device scan. Must be an AISG Port object.
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_DeviceScan(ORI_s * ori, ORI_Object_s * object, ORI_Result_e * RE_result);

/**
 * @brief Transfer an AISG layer7 message to an ALD.
 *
 * This function transfers an AISG layer7 message to an ALD.
 * On completion of the transfer, the RE shall send a message indicating the ALD's layer7 response.
 *
 * @param ori The ORI context.
 * @param object The object targeted for the layer7 message. Must be an AISG ALD object.
 * @param msgLayer7 The AISG layer7 message.
 * @param deviceDataFieldNbr The field number to store for GetDeviceData message (used in indication parsing).
 * @param RE_result The RE response result of the procedure.
 * @return The result of the procedure.
 */
ORI_Result_e ORI_MsgTransfer(ORI_s * ori, ORI_Object_s * object, const char * msgLayer7, uint8_t deviceDataFieldNbr, ORI_Result_e * RE_result);



/*-----------------------------------------------------------------------------------------
 * ORI MODEL
 *-----------------------------------------------------------------------------------------*/

/**
 * @brief Find an object in the model.
 *
 * This function seeks in the model an object that matches the object type @p type
 * and the instance number @p instanceNumber. <br>
 * If @p parent is @c NULL, only parent-less objects will be in the search. Else, the object
 * to find shall be a direct descendant of @p parent.
 *
 * @param ori The ORI context.
 * @param type The object type of the object to find.
 * @param instanceNumber The instance number of the object to find.
 * @param parent The parent of the object to find, or @c NULL if no parent is expected.
 * @return The found object if any, or @c NULL if none.
 */
ORI_Object_s * ORI_FindObject(ORI_s * ori, ORI_ObjectType_e type, uint8_t instanceNumber, ORI_Object_s * parent);

/**
 * @brief Gets all objects in the model
 *
 * This function fills the array @p objects with reference of all the objects in the model that are a child of @p parent. If @p parent is @c NULL,
 * all the objects in the model are retrieved. <br>
 * The maximum size of the @p objects array shall be given in @p maxObjects. <br>
 *
 * @param ori The ORI context.
 * @param objects The object array to fill.
 * @param maxObjects The maximum number of objects that the array can contain.
 * @param parent If not @c NULL, specifies the parent of the objects to get.
 * @return The number of objects found.
 */
uint32_t ORI_GetAllObjects(ORI_s * ori, ORI_Object_s * objects[], uint32_t maxObjects, ORI_Object_s * parent);

/**
 * @brief Gets all objects of a given type in the model
 *
 * This function fills the array @p objects with reference of all the objects of type @p type in the model that are a child of @p parent. If @p parent is @c NULL,
 * all the objects of type @p type in the model are retrieved. <br>
 * The maximum size of the @p objects array shall be given in @p maxObjects. <br>
 * This functions is the same as ORI_GetAllObjects() but with a type filter.
 *
 * @param ori The ORI context.
 * @param type The type filter of the objects to find.
 * @param objects The object array to fill.
 * @param maxObjects The maximum number of objects that the array can contain.
 * @param parent If not @c NULL, specifies the parent of the objects to get.
 * @return The number of objects found.
 */
uint32_t ORI_GetAllObjectsOfType(ORI_s * ori, ORI_ObjectType_e type, ORI_Object_s * objects[], uint32_t maxObjects, ORI_Object_s * parent);

/**
 * @brief Return the fault structure of an object based on a fault type.
 *
 * This function is a helper function that returns a pointer to a fault structure of an object based on a fault type.
 * If the fault type and the object type does not match (as faults are specific to some objects), @c NULL is returned.
 *
 * @param ori The ORI context.
 * @param object The object to delete.
 * @param faultType The type of the fault structure to return.
 * @return The found fault structure, or @c NULL if none.
 */
ORI_Fault_s * ORI_ObjectFault(ORI_s * ori, ORI_Object_s * object, ORI_FaultType_e faultType);




#endif /* ORI_H_ */