irobotError.h

00001 /** \file irobotError.h
00002  *
00003  * iRobot error handling and codes.
00004  *
00005  * \author Jeff C. Jensen
00006  * \date 2013-12-09
00007  * \copyright Copyright (C) 2013, Jeff C. Jensen, Edward A. Lee, and Sanjit A. Seshia.
00008  *            This software accompanies An Introductory Lab in Embedded and Cyber-Physical Systems
00009  *            and is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0
00010  *            Unported License. See http://leeseshia.org/lab.
00011  */
00012 
00013 #ifndef _IROBOTERROR_H
00014 #define _IROBOTERROR_H
00015 
00016 #include "irobotTypes.h"
00017 
00018 #ifndef ERROR_SUCCESS
00019 /// Operation successful
00020 #define ERROR_SUCCESS               0
00021 #endif
00022 
00023 #ifndef ERROR_INVALID_PARAMETER
00024 /// Operation received an invalid parameter
00025 #define ERROR_INVALID_PARAMETER     -52005
00026 #endif
00027 
00028 #ifndef ERROR_TIMEOUT
00029 /// Operation timed out
00030 #define ERROR_TIMEOUT               -50400
00031 #endif
00032 
00033 
00034 /**
00035  * Tests whether a status is an error.
00036  *
00037  * @param status status to check for an error
00038  * @return whether the status was an error
00039  */
00040 #define irobot_IsError(status)  ((status) < ERROR_SUCCESS)
00041 
00042 /**
00043  * Conditionally sets the status to a new value. The previous status is
00044  * preserved unless the new status is more of an error, which means that
00045  * warnings and errors overwrite successes, and errors overwrite warnings. New
00046  * errors do not overwrite older errors, and new warnings do not overwrite
00047  * older warnings.
00048  *
00049  * @param status status to conditionally set
00050  * @param newStatus new status value that may be set
00051  * @return the resulting status
00052  */
00053 int32_t irobot_StatusMerge(int32_t * const status, const int32_t newStatus);
00054 
00055 /**
00056  * This macro evaluates the expression only if the status is not an error. The
00057  * expression must evaluate to a int32_t, because the status will be set to the
00058  * returned status if the expression is evaluated.
00059  *
00060  * You can use this macro to mimic status chaining:
00061  *
00062  *    int32_t status = ERROR_SUCCESS;
00063  *    IfIsNotError(&status, SendMessage(...));
00064  *    IfIsNotError(&status, SendMessage(...));
00065  *    IfIsNotError(&status, SendMessage(...));
00066  *
00067  * @param status status to check for an error
00068  * @param expression expression to call if the incoming status is not an error
00069  */
00070 #define irobot_IfIsNotError(status, expression) \
00071    if(!irobot_IsError(status)) \
00072    { \
00073        irobot_StatusMerge(&status, (expression)); \
00074    }
00075 
00076 
00077 #endif // _IROBOTERROR_H