3.5. Parameter Check & Conventions¶
3.5.1. Parameter Convention¶
APIs for which a buffer is input. e.g.:
smStatus_t Se05x_API_VerifySessionUserID(
pSe05xSession_t session_ctx,
const uint8_t *userId,
size_t userIdLen);
In the above case userId
is a buffer input. It is assumed that
the lengh as set in userIdLen
is same as that pointed to by
userId
. This parameter is used as is and any mistake by the calling
API will have unpredictable errors.
APIs for which a buffer is input. e.g.:
smStatus_t Se05x_API_ReadObject(
pSe05xSession_t session_ctx,
uint32_t objectID,
uint16_t offset,
uint16_t length,
uint8_t *data,
size_t *pdataLen);
In the above case data
is a buffer output and pdataLen
is both
input and output. It is assumed that the lengh as set in pdataLen
is
set to the maximum as available to the pointer pointed by data
. This
parameter is used as is and any mistake by the calling API will have
unpredictable errors.
3.5.1.1. PCSC/CCID Interface and 64 Byte packet¶
See the note “USB 64 byte boundary” at hostlib\\hostLib\\libCommon\\smCom\\smComPCSC.c
3.5.2. Helper Macros¶
Helper macros are available as a part of the stack to capture warnings if some parameters are not as expected.
During debug builds, it is recommended to enable the logging to capture mistakes during integration.
During Retail/Release builds, they may be kept silent.
3.5.3. Apis¶
-
group
param_check
Parameter Checks.
nxEnsure.h: Helper parameter assertion check macros.
Pre Condition: The source file must have included nxLog header file.
Project: SecureIoTMW
Defines
-
ENSURE_OR_BREAK
(CONDITION) If condition fails, break.
Sample Usage:
int SomeAPI() { ... do { status = Operation1(); ENSURE_OR_BREAK(0 == status); status = Operation2(); ENSURE_OR_BREAK(0 == status); ... } while(0); return status; }
-
ENSURE_OR_EXIT_WITH_STATUS_ON_ERROR
(CONDITION, STATUS, RETURN_VALUE) If condition fails, goto quit with return value status updated.
int SomeAPI() { int status = 0; ... value = Operation1(); ENSURE_OR_QUIT_WITH_STATUS_ON_ERROR(0 == value, status, ERR_FAIL); value = Operation2(); ENSURE_OR_QUIT_WITH_STATUS_ON_ERROR(0 == value, status, ERR_NOT_ENOUGH_SPACE); ... quit: return status; }
- Warning
This macro introduces system of mutliple returns from a function which is not easy to debug/trace through and hence not recommended.
-
ENSURE_OR_GO_CLEANUP
(CONDITION) If condition fails, goto :cleanup label
{ ... status = Operation1(); ENSURE_OR_GO_CLEANUP(0 == status); status = Operation2(); ENSURE_OR_GO_CLEANUP(0 == status); ... cleanup: return status; }
-
ENSURE_OR_GO_EXIT
(CONDITION) If condition fails, goto :exit label
{ ... status = Operation1(); ENSURE_OR_GO_EXIT(0 == status); status = Operation2(); ENSURE_OR_GO_EXIT(0 == status); ... exit: return status; }
-
ENSURE_OR_RETURN
(CONDITION) If condition fails, return
void SomeAPI() { ... status = Operation1(); ENSURE_OR_RETURN(0 == status); status = Operation2(); ENSURE_OR_RETURN(0 == status); ... return; }
- Warning
This macro introduces system of mutliple returns from a function which is not easy to debug/trace through and hence not recommended.
-
ENSURE_OR_RETURN_ON_ERROR
(CONDITION, RETURN_VALUE) If condition fails, return
int SomeAPI() { ... status = Operation1(); ENSURE_OR_RETURN_ON_ERROR(0 == status, ERR_FAIL); status = Operation2(); ENSURE_OR_RETURN_ON_ERROR(0 == status, ERR_NOT_ENOUGH_SPACE); ... return 0; }
- Warning
This macro introduces system of mutliple returns from a function which is not easy to debug/trace through and hence not recommended.
-
NX_ENSURE_DO_LOG_MESSAGE
Build time over-ride if we want to enable/disable Warning Prints
During debug builds, it makes sense to print them, During retail builds, such loggings would be of any use and remove and reduce code size.
-
NX_ENSURE_MESSAGE
(strCONDITION) Waring print of the parameter
strCONDITION
- Warning
NX_ENSURE_MESSAGE is an internal message/API to this file. Do not use directly.
-
NX_ENSURE_MESSAGE
(strCONDITION) Waring print of the parameter
strCONDITION
- Warning
NX_ENSURE_MESSAGE is an internal message/API to this file. Do not use directly.
-