The Meaning of SUCCESS

When an operation returns a SUCCESS indication (either synchronously upon function return for synchronous operations, or asynchronously with a call to the ASYNC_COMPLETION callback procedure for asynchronous operations), then the following are assumed to be true:

• The function has successfully progressed up to a service-provider-defined point. The service provider defines the point on a function-by-function basis. After reaching that point, either the operation is completely finished, or it is in a state such that subsequent independent state messages will inform the application about progress.
• Functions that return information (such as TSPI_linePark or TSPI_lineDevSpecific) return SUCCESS only when the requested information is available to the caller. Functions that return handles (to opened lines, opened phones, or calls) return the handles immediately on function return. Both the service provider and the caller must treat the handles as "not yet valid" until the eventual SUCCESS indication. The service provider is responsible for preventing any callback messages to the LINEEVENT or PHONEEVENT procedure about that opened line, opened phone, or call until after the SUCCESS indication. If the eventual result is an error, any handle returned immediately becomes invalid without any further action.
• Functions that enable certain permanent conditions (like TSPI_lineMonitorDigits) return SUCCESS only after the condition is enabled, not when the condition is removed again (for example, not when digit monitoring is complete).
• Call control functions (such as TSPI_lineHold and TSPI_lineSetupTransfer, but not TSPI_lineMakeCall) return SUCCESS when the operation is completed. In telephony environments that do not provide positive acknowledgment of these functions, the service provider is forced to make a best-effort decision as to the success or failure of the function.
• A service provider's implementation of TSPI_lineMakeCall must return SUCCESS no later than when the call enters the proceeding call state. Ideally, the provider indicates SUCCESS as soon as possible, such as when the call enters the dialtone call state (if applicable). When SUCCESS is returned to the application, LINE_CALLSTATE messages inform the caller about the progress of the call. Service providers that delay returning the TSPI_lineMakeCall SUCCESS indication, for example, until after dialing is complete, severely limit flexibility at the application level. Delay in returning SUCCESS in TSPI_lineMakeCall prevents a user from canceling the call setup request in progress until after dialing is complete, and all digits are sent to the switch.