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.