mirror of
https://github.com/espressif/openthread.git
synced 2026-08-29 13:29:54 +00:00
Cleanup error code usage. Avoid raising errors when value is unchanged. (#787)
This change is attempting to address two issues:
1. Returning `kThreadError_Busy`, when `kThreadError_Already`,
`kThreadError_InvalidState`, or even the lazy
`kThreadError_Failed` would be more-appropriate/less-misleading.
2. Setters returning an error when the value to be changed is already
set to the requested value.
Number one hurts debuggability. Number two makes the code more fragile.
The cases where both intersect can be maddening.
This change replaces cases inappropriately returning
`kThreadError_Busy` with a better, more specific error code. It also
makes some "setter" functions (Including `otInterfaceUp()` and
`otThreadStart()`) return success if the value is already set.
This commit is contained in:
Robert Quattlebaum
committed by
Jonathan Hui
Jonathan Hui
parent
2d5c4c58f2
commit
104ca6d10d
@@ -157,6 +157,11 @@ typedef enum ThreadError
|
||||
*/
|
||||
kThreadError_Ipv6AddressCreationFailure = 28,
|
||||
|
||||
/**
|
||||
* Operation prevented by mode flags
|
||||
*/
|
||||
kThreadError_NotCapable = 29,
|
||||
|
||||
kThreadError_Error = 255,
|
||||
} ThreadError;
|
||||
|
||||
|
||||
+23
-19
@@ -206,8 +206,8 @@ void otInstanceFinalize(otInstance *aInstance);
|
||||
*
|
||||
* @param[in] aInstance A pointer to an OpenThread instance.
|
||||
*
|
||||
* @retval kThreadError_None Successfully enabled the IPv6 interface.
|
||||
* @retval kThreadError_InvalidState OpenThread is not enabled or the IPv6 interface is already up.
|
||||
* @retval kThreadError_None Successfully enabled the IPv6 interface,
|
||||
* or the interface was already enabled.
|
||||
*
|
||||
*/
|
||||
ThreadError otInterfaceUp(otInstance *aInstance);
|
||||
@@ -219,8 +219,8 @@ ThreadError otInterfaceUp(otInstance *aInstance);
|
||||
*
|
||||
* @param[in] aInstance A pointer to an OpenThread instance.
|
||||
*
|
||||
* @retval kThreadError_None Successfully brought the interface down.
|
||||
* @retval kThreadError_InvalidState The interface was not up.
|
||||
* @retval kThreadError_None Successfully brought the interface down,
|
||||
* or the interface was already down.
|
||||
*
|
||||
*/
|
||||
ThreadError otInterfaceDown(otInstance *aInstance);
|
||||
@@ -244,7 +244,7 @@ bool otIsInterfaceUp(otInstance *aInstance);
|
||||
* @param[in] aInstance A pointer to an OpenThread instance.
|
||||
*
|
||||
* @retval kThreadError_None Successfully started Thread protocol operation.
|
||||
* @retval kThreadError_InvalidState Thread protocol operation is already started or the interface is not up.
|
||||
* @retval kThreadError_InvalidState The network interface was not not up.
|
||||
*
|
||||
*/
|
||||
ThreadError otThreadStart(otInstance *aInstance);
|
||||
@@ -255,7 +255,6 @@ ThreadError otThreadStart(otInstance *aInstance);
|
||||
* @param[in] aInstance A pointer to an OpenThread instance.
|
||||
*
|
||||
* @retval kThreadError_None Successfully stopped Thread protocol operation.
|
||||
* @retval kThreadError_InvalidState The Thread protocol operation was not started.
|
||||
*
|
||||
*/
|
||||
ThreadError otThreadStop(otInstance *aInstance);
|
||||
@@ -430,14 +429,17 @@ uint8_t otGetMaxAllowedChildren(otInstance *aInstance);
|
||||
/**
|
||||
* Set the maximum number of children currently allowed.
|
||||
*
|
||||
* This parameter can only be set when Thread protocol operation
|
||||
* has been stopped.
|
||||
*
|
||||
* @param[in] aInstance A pointer to an OpenThread instance.
|
||||
* @param[in] aMaxChildren The maximum allowed children.
|
||||
*
|
||||
* @retval kThreadErrorNone Successfully set the max.
|
||||
* @retval kThreadError_InvalidArgs If @p aMaxChildren is not in the range [1, OPENTHREAD_CONFIG_MAX_CHILDREN].
|
||||
* @retval kThreadError_InvalidState If Thread has already been started.
|
||||
* @retval kThreadError_InvalidState If Thread isn't stopped.
|
||||
*
|
||||
* @sa otGetMaxAllowedChildren
|
||||
* @sa otGetMaxAllowedChildren, otThreadStop
|
||||
*/
|
||||
ThreadError otSetMaxAllowedChildren(otInstance *aInstance, uint8_t aMaxChildren);
|
||||
|
||||
@@ -1450,8 +1452,8 @@ bool otIsMacWhitelistEnabled(otInstance *aInstance);
|
||||
*
|
||||
* @param[in] aInstance A pointer to an OpenThread instance.
|
||||
*
|
||||
* @retval kThreadErrorNone Successfully detached from the Thread network.
|
||||
* @retval kThreadErrorBusy Thread is disabled.
|
||||
* @retval kThreadErrorNone Successfully detached from the Thread network.
|
||||
* @retval kThreadErrorInvalidState Thread is disabled.
|
||||
*/
|
||||
ThreadError otBecomeDetached(otInstance *aInstance);
|
||||
|
||||
@@ -1461,8 +1463,8 @@ ThreadError otBecomeDetached(otInstance *aInstance);
|
||||
* @param[in] aInstance A pointer to an OpenThread instance.
|
||||
* @param[in] aFilter Identifies whether to join any, same, or better partition.
|
||||
*
|
||||
* @retval kThreadErrorNone Successfully begin attempt to become a child.
|
||||
* @retval kThreadErrorBusy Thread is disabled or in the middle of an attach process.
|
||||
* @retval kThreadErrorNone Successfully begin attempt to become a child.
|
||||
* @retval kThreadErrorInvalidState Thread is disabled.
|
||||
*/
|
||||
ThreadError otBecomeChild(otInstance *aInstance, otMleAttachFilter aFilter);
|
||||
|
||||
@@ -1471,8 +1473,8 @@ ThreadError otBecomeChild(otInstance *aInstance, otMleAttachFilter aFilter);
|
||||
*
|
||||
* @param[in] aInstance A pointer to an OpenThread instance.
|
||||
*
|
||||
* @retval kThreadErrorNone Successfully begin attempt to become a router.
|
||||
* @retval kThreadErrorBusy Thread is disabled or already operating in a router or leader role.
|
||||
* @retval kThreadErrorNone Successfully begin attempt to become a router.
|
||||
* @retval kThreadErrorInvalidState Thread is disabled.
|
||||
*/
|
||||
ThreadError otBecomeRouter(otInstance *aInstance);
|
||||
|
||||
@@ -1481,7 +1483,8 @@ ThreadError otBecomeRouter(otInstance *aInstance);
|
||||
*
|
||||
* @param[in] aInstance A pointer to an OpenThread instance.
|
||||
*
|
||||
* @retval kThreadErrorNone Successfully became a leader and started a new partition.
|
||||
* @retval kThreadErrorNone Successfully became a leader and started a new partition.
|
||||
* @retval kThreadErrorInvalidState Thread is disabled.
|
||||
*/
|
||||
ThreadError otBecomeLeader(otInstance *aInstance);
|
||||
|
||||
@@ -1878,8 +1881,9 @@ bool otIsLinkPromiscuous(otInstance *aInstance);
|
||||
* @param[in] aInstance A pointer to an OpenThread instance.
|
||||
* @param[in] aPromiscuous true to enable promiscuous mode, or false otherwise.
|
||||
*
|
||||
* @retval kThreadError_None Successfully enabled promiscuous mode.
|
||||
* @retval kThreadError_Busy Could not enable promiscuous mode because the Thread interface is enabled.
|
||||
* @retval kThreadError_None Successfully enabled promiscuous mode.
|
||||
* @retval kThreadError_InvalidState Could not enable promiscuous mode because
|
||||
* the Thread interface is enabled.
|
||||
*
|
||||
*/
|
||||
ThreadError otSetLinkPromiscuous(otInstance *aInstance, bool aPromiscuous);
|
||||
@@ -2243,8 +2247,8 @@ otMessage otNewUdpMessage(otInstance *aInstance);
|
||||
* @param[in] aCallback A pointer to the application callback function.
|
||||
* @param[in] aContext A pointer to application-specific context.
|
||||
*
|
||||
* @retval kThreadErrorNone Successfully opened the socket.
|
||||
* @retval kThreadErrorBusy Socket is already opened.
|
||||
* @retval kThreadErrorNone Successfully opened the socket.
|
||||
* @retval kThreadErrorInvalidArgs Given socket structure was already opened.
|
||||
*
|
||||
* @sa otNewUdpMessage
|
||||
* @sa otCloseUdpSocket
|
||||
|
||||
@@ -203,8 +203,8 @@ void otPlatRadioSetShortAddress(otInstance *aInstance, uint16_t aShortAddress);
|
||||
*
|
||||
* @param[in] aInstance The OpenThread instance structure.
|
||||
*
|
||||
* @retval ::kThreadError_None Successfully transitioned to Sleep.
|
||||
* @retval ::kThreadError_Busy The radio was already enabled.
|
||||
* @retval ::kThreadError_None Successfully enabled.
|
||||
* @retval ::kThreadError_Failure The radio could not be enabled.
|
||||
*/
|
||||
ThreadError otPlatRadioEnable(otInstance *aInstance);
|
||||
|
||||
@@ -233,8 +233,9 @@ bool otPlatRadioIsEnabled(otInstance *aInstance);
|
||||
*
|
||||
* @param[in] aInstance The OpenThread instance structure.
|
||||
*
|
||||
* @retval ::kThreadError_None Successfully transitioned to Sleep.
|
||||
* @retval ::kThreadError_Busy The radio was not in the Receive state.
|
||||
* @retval ::kThreadError_None Successfully transitioned to Sleep.
|
||||
* @retval ::kThreadError_Busy The radio was transmitting
|
||||
* @retval ::kThreadError_InvalidState The radio was disabled
|
||||
*/
|
||||
ThreadError otPlatRadioSleep(otInstance *aInstance);
|
||||
|
||||
@@ -245,8 +246,8 @@ ThreadError otPlatRadioSleep(otInstance *aInstance);
|
||||
* @param[in] aInstance The OpenThread instance structure.
|
||||
* @param[in] aChannel The channel to use for receiving.
|
||||
*
|
||||
* @retval ::kThreadError_None Successfully transitioned to Receive.
|
||||
* @retval ::kThreadError_Busy The radio was not in the Sleep state.
|
||||
* @retval ::kThreadError_None Successfully transitioned to Receive.
|
||||
* @retval ::kThreadError_InvalidState The radio was disabled or transmitting.
|
||||
*/
|
||||
ThreadError otPlatRadioReceive(otInstance *aInstance, uint8_t aChannel);
|
||||
|
||||
@@ -355,7 +356,7 @@ RadioPacket *otPlatRadioGetTransmitBuffer(otInstance *aInstance);
|
||||
* @param[in] aInstance The OpenThread instance structure.
|
||||
*
|
||||
* @retval ::kThreadError_None Successfully transitioned to Transmit.
|
||||
* @retval ::kThreadError_Busy The radio was not in the Receive state.
|
||||
* @retval ::kThreadError_InvalidState The radio was not in the Receive state.
|
||||
*/
|
||||
ThreadError otPlatRadioTransmit(otInstance *aInstance);
|
||||
|
||||
|
||||
Reference in New Issue
Block a user