Represents an outstanding, asynchronous operation. More...
Modules | |
| DOFOperationBridgeConfig | |
| The DOFOperationBridgeConfig class represents a security bridge configuration. | |
| DOFOperationControl | |
| Specifies the control parameters of a Request Operation. | |
| DOFOperationFilter | |
| The DOFOperationFilter class represents an operation filter. | |
Files | |
| file | oal.h |
| Header file for the C OAL functions, defines and data types. | |
Typedefs | |
| typedef struct DOFOperation_t * | DOFOperation |
| Represents an asynchronous operation. | |
| typedef struct DOFOperationFilter_t * | DOFOperationFilter |
| A type to filter unwanted DOFOperations. | |
| typedef struct DOFOperationFilterBuilder_t * | DOFOperationFilterBuilder |
| A type to build and configure a DOFOperationFilter. | |
| typedef struct DOFOperationBridgeConfig_t * | DOFOperationBridgeConfig |
| A type to control the DOFDomain a DOFOperation is presented in. | |
| typedef struct DOFOperationBridgeConfigBuilder_t * | DOFOperationBridgeConfigBuilder |
| A type to build and configure a DOFOperationBridgeConfig. | |
Functions | |
| void | DOFOperation_Cancel (DOFOperation op) |
| Cancel an Operation. | |
| void | DOFOperation_Destroy (DOFOperation op) |
| Destroy an Operation, freeing the Operation's resources. | |
| void * | DOFOperation_GetContext (const DOFOperation op) |
| Return the application's context information held within the Operation. | |
| uint32 | DOFOperation_GetTimeRemaining (const DOFOperation op) |
| Report the Operation's remaining timeout, in milliseconds. | |
| boolean | DOFOperation_SetTimeout (DOFOperation op, uint32 timeout) |
| Set or change an Operation's timeout. | |
| boolean | DOFOperation_IsCancelled (const DOFOperation op) |
| Report whether or not the Operation is cancelled. | |
| boolean | DOFOperation_IsComplete (const DOFOperation op) |
| Report whether or not the Operation is complete. | |
| boolean | DOFOperation_IsAcknowledged (const DOFOperation op) |
| Report whether or not the Operation is acknowledged. | |
| boolean | DOFOperation_WaitComplete (const DOFOperation op, uint32 timeout, DOFException *pException) |
| Wait for the Operation to complete. | |
| boolean | DOFOperation_WaitAcknowledged (const DOFOperation op, uint32 timeout, DOFException *pException) |
| Wait for the Operation to be acknowledged. | |
| DOFException | DOFOperation_GetException (const DOFOperation op) |
| Get the exception associated with a completed operation, if any. | |
DOFOperation.Get | |
These calls are only for Get Operations (resulting from a DOFObject_BeginGet call). | |
| DOFObject | DOFOperationGet_GetObject (const DOFOperation op) |
| Return the DOFObject that is associated with the Get Operation. | |
| DOFInterfaceProperty | DOFOperationGet_GetProperty (const DOFOperation op) |
| Return the DOFInterfaceProperty that is associated with the Get Operation. | |
| DOFOperationControl | DOFOperationGet_GetControl (const DOFOperation op) |
| Return the DOFOperationControl that is associated with the Get Operation. | |
| DOFResult | DOFOperationGet_WaitResult (const DOFOperation op, uint32 timeout, DOFException *pException) |
| Wait for and return the result of the Get Operation. | |
| DOFResult | DOFOperationGet_GetResult (const DOFOperation op, DOFException *pException) |
| Return the result of the Get Operation, if any. | |
DOFOperation.Set | |
These calls are only for Set Operations (resulting from a DOFObject_BeginSet call). | |
| DOFObject | DOFOperationSet_GetObject (const DOFOperation op) |
| Return the DOFObject that is associated with the Set Operation. | |
| DOFInterfaceProperty | DOFOperationSet_GetProperty (const DOFOperation op) |
| Return the DOFInterfaceProperty that is associated with the Set Operation. | |
| DOFOperationControl | DOFOperationSet_GetControl (const DOFOperation op) |
| Return the DOFOperationControl that is associated with the Set Operation. | |
| DOFResult | DOFOperationSet_WaitResult (const DOFOperation op, uint32 timeout, DOFException *pException) |
| Wait for and return the result of the Set Operation. | |
| DOFResult | DOFOperationSet_GetResult (const DOFOperation op, DOFException *pException) |
| Return the result of the Set Operation, if any. | |
DOFOperation.Invoke | |
These calls are only for Invoke Operations (resulting from a DOFObject_BeginInvoke call). | |
| DOFObject | DOFOperationInvoke_GetObject (const DOFOperation op) |
| Return the DOFObject that is associated with the Invoke Operation. | |
| DOFInterfaceMethod | DOFOperationInvoke_GetMethod (const DOFOperation op) |
| Return the DOFInterfaceMethod that is associated with the Invoke Operation. | |
| DOFOperationControl | DOFOperationInvoke_GetControl (const DOFOperation op) |
| Return the DOFOperationControl that is associated with the Invoke Operation. | |
| DOFResult | DOFOperationInvoke_WaitResult (const DOFOperation op, uint32 timeout, DOFException *pException) |
| Wait for and return the result of the Invoke Operation. | |
| DOFResult | DOFOperationInvoke_GetResult (const DOFOperation op, DOFException *pException) |
| Return the result of the Invoke Operation, if any. | |
DOFOperation.Subscribe | |
These calls are only for Subscribe Operations (resulting from a DOFObject_BeginSubscribe call). | |
| DOFObject | DOFOperationSubscribe_GetObject (const DOFOperation op) |
| Return the DOFObject that is associated with the Subscribe Operation. | |
| DOFInterfaceProperty | DOFOperationSubscribe_GetProperty (const DOFOperation op) |
| Return the DOFInterfaceProperty that is associated with the Subscribe Operation. | |
| DOFOperationControl | DOFOperationSubscribe_GetControl (const DOFOperation op) |
| Return the DOFOperationControl that is associated with the Subscribe Operation. | |
| uint32 | DOFOperationSubscribe_GetMinPeriod (const DOFOperation op) |
| Return the minimum period that was specified with the Subscribe Operation. | |
DOFOperation.Register | |
These calls are only for Register Operations (resulting from a DOFObject_BeginRegister call). | |
| DOFObject | DOFOperationRegister_GetObject (const DOFOperation op) |
| Return the DOFObject that is associated with the Register Operation. | |
| DOFInterfaceEvent | DOFOperationRegister_GetEvent (const DOFOperation op) |
| Return the DOFInterfaceEvent that is associated with the Register Operation. | |
| DOFOperationControl | DOFOperationRegister_GetControl (const DOFOperation op) |
| Return the DOFOperationControl that is associated with the Register Operation. | |
DOFOperation.Session | |
These calls are only for Session Operations (resulting from a DOFObject_BeginSession call). | |
| DOFObject | DOFOperationSession_WaitSession (const DOFOperation op, uint32 timeout, DOFException *pException) |
| Wait for a Session Operation to be accepted, and return a DOFObject for the session. | |
| DOFObject | DOFOperationSession_GetObject (const DOFOperation op) |
| Return the DOFObject that is associated with the Session Operation. | |
| DOFInterface | DOFOperationSession_GetInterface (const DOFOperation op) |
| Return the DOFInterface that is associated with the Session Operation. | |
| DOFInterfaceID | DOFOperationSession_GetSessionType (const DOFOperation op) |
| Return the Session's type (a DOFInterfaceID) that is associated with the Session Operation. | |
| DOFOperationControl | DOFOperationSession_GetControl (const DOFOperation op) |
| Return the DOFOperationControl that is associated with the Session Operation. | |
| boolean | DOFOperationSession_SetDataTransform (DOFOperation sessionOperation, DOFOperationSessionDataTransform transform) |
| Set the DOFOperationSessionDataTransform to use on this session. | |
DOFOperation.Provide | |
These calls are only for Provide Operations (resulting from a DOFObject_BeginProvide call). | |
| DOFObject | DOFOperationProvide_GetObject (const DOFOperation op) |
| Return the DOFObject that is associated with the Provide Operation. | |
| DOFInterface | DOFOperationProvide_GetInterface (const DOFOperation op) |
| Return the DOFInterface that is associated with the Provide Operation. | |
DOFOperation.Interest | |
These calls are only for Interest Operations (resulting from a DOFSystem_BeginInterest call). | |
| DOFSystem | DOFOperationInterest_GetSystem (const DOFOperation op) |
| Return the DOFSystem that is associated with the Interest Operation. | |
| DOFObjectID | DOFOperationInterest_GetObjectID (const DOFOperation op) |
| Return the DOFObjectID that is associated with the Interest Operation. | |
| DOFInterfaceID | DOFOperationInterest_GetInterfaceID (DOFOperation op) |
| Return the DOFInterfaceID that is associated with the Interest Operation. | |
| DOFInterestLevel | DOFOperationInterest_GetInterestLevel (const DOFOperation op) |
| Return the DOFInterestLevel that is associated with the Interest Operation. | |
| DOFOperationControl | DOFOperationInterest_GetControl (const DOFOperation op) |
| Return the DOFOperationControl that is associated with the Interest Operation. | |
DOFOperation.Define | |
These calls are only for Define Operations (resulting from a DOFObject_BeginDefine call). | |
| DOFInterface | DOFOperationDefine_WaitInterface (const DOFOperation op, uint32 timeout, DOFException *pException) |
| Wait for and return the interface definition of the Define Operation. | |
| DOFObject | DOFOperationDefine_GetObject (const DOFOperation op) |
| Return the DOFObject that is associated with the Define Operation. | |
| DOFInterfaceID | DOFOperationDefine_GetInterfaceID (const DOFOperation op) |
| Return the DOFInterfaceID that is associated with the Define Operation. | |
| DOFOperationControl | DOFOperationDefine_GetControl (const DOFOperation op) |
| Return the DOFOperationControl that is associated with the Define Operation. | |
DOFOperation.Query | |
These calls are only for Query Operations (resulting from a DOFSystem_BeginQuery call). | |
| DOFQuery | DOFOperationQuery_GetQuery (const DOFOperation op) |
| Return the DOFQuery that is associated with a Query Operation. | |
| DOFSystem | DOFOperationQuery_GetSystem (const DOFOperation op) |
| Return the DOFSystem that is associated with the Query Operation. | |
Represents an outstanding, asynchronous operation.
The following model is used for all asynchronous operations (that continue in a separate thread while the initiator can do other things):
DOFOperation <type>_Begin<op>( <parameters>, uint32 timeout, <callback(s)>, void * context )
The timeout parameter represents the amount of time that the operation is permitted to continue. It is represented in milliseconds. In general, a timeout of 0 indicates that the operation is carried out but immediately times out, prior to any response or other normal completion. Conversely, a timeout of DOF_TIMEOUT_NEVER indicates that the operation never times out. The timeout can be changed via DOFOperation_SetTimeout any time before it has completed. Once the operation is complete, attempting to change the timeout will have no effect.
The callback parameter represents an object containing a set of function pointers (depending on the call) that will be called as the operation either completes or reports its status or result data. The object may also contain state or other data associated with the functions, but it should not be specific to the operation.
The context parameter represents data, associated with the specific operation, that is passed from the call point to the callback. This allows state specific to the operation to be available inside the callbacks. Thus, the same callback may be used for multiple, different operations, and the callback can determine the appropriate behavior based on the operation's context.
The DOFOperation represents the operation itself, and is the application's handle to control the operation's lifecycle and access the context. In addition to changing their timeout (as already indicated), Operations can also be cancelled via DOFOperation_Cancel, in which case the operation is immediately marked as complete. If an Operation is not yet complete when it is passed to DOFOperation_Destroy, it will first be cancelled, prior to being deallocated.
Most Operations complete with the response of requested data. Some operations, such as a Provide or Query operation, only complete due to a timeout or a cancellation. Multicast operations using the Wildcard Object ID may solicit multiple responses, and thus will persist until they time out or are cancelled.
In all circumstances, the Operation must eventually be complete, triggering the invocation of the complete callback. In some cases, the callback may extend the operation's timeout (if the operation only timed out), thereby causing the operation to continue and the complete callback to be called once again (after the new timeout). If the complete callback returns without extending the operation's timeout, then the Operation is flagged as complete (DOFOperation_IsComplete returns TRUE).
It is up to the application to eventually free the resources associated with the Operation. It is generally not recommended to destroy the DOFOperation from within the callback, as this can cause memory corruption if the operation is still being used by the application (e.g., in another thread). However, if the application "passes" ownership to the callback to manage the lifecycle, then the operation can safely be destroyed inside the callback.