path: root/libs/binder/ndk/include_ndk/android/binder_status.h

/*
 * Copyright (C) 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup NdkBinder
 * @{
 */

/**
 * @file binder_status.h
 */

#pragma once

#include <errno.h>
#include <stdbool.h>
#include <stdint.h>
#include <sys/cdefs.h>

__BEGIN_DECLS

#ifndef __ANDROID_API__
#error Android builds must be compiled against a specific API. If this is an \
 android platform host build, you must use libbinder_ndk_host_user.
#endif

/**
 * Low-level status types for use in binder. This is the least preferable way to
 * return an error for binder services (where binder_exception_t should be used,
 * particularly EX_SERVICE_SPECIFIC).
 */
enum {
    STATUS_OK = 0,

    STATUS_UNKNOWN_ERROR = (-2147483647 - 1),  // INT32_MIN value
    STATUS_NO_MEMORY = -ENOMEM,
    STATUS_INVALID_OPERATION = -ENOSYS,
    STATUS_BAD_VALUE = -EINVAL,
    STATUS_BAD_TYPE = (STATUS_UNKNOWN_ERROR + 1),
    STATUS_NAME_NOT_FOUND = -ENOENT,
    STATUS_PERMISSION_DENIED = -EPERM,
    STATUS_NO_INIT = -ENODEV,
    STATUS_ALREADY_EXISTS = -EEXIST,
    STATUS_DEAD_OBJECT = -EPIPE,
    STATUS_FAILED_TRANSACTION = (STATUS_UNKNOWN_ERROR + 2),
    STATUS_BAD_INDEX = -EOVERFLOW,
    STATUS_NOT_ENOUGH_DATA = -ENODATA,
    STATUS_WOULD_BLOCK = -EWOULDBLOCK,
    STATUS_TIMED_OUT = -ETIMEDOUT,
    STATUS_UNKNOWN_TRANSACTION = -EBADMSG,
    STATUS_FDS_NOT_ALLOWED = (STATUS_UNKNOWN_ERROR + 7),
    STATUS_UNEXPECTED_NULL = (STATUS_UNKNOWN_ERROR + 8),
};

/**
 * One of the STATUS_* values.
 *
 * All unrecognized values are coerced into STATUS_UNKNOWN_ERROR.
 */
typedef int32_t binder_status_t;

/**
 * Top level exceptions types for Android binder errors, mapping to Java
 * exceptions. Also see Parcel.java.
 */
enum {
    EX_NONE = 0,
    EX_SECURITY = -1,
    EX_BAD_PARCELABLE = -2,
    EX_ILLEGAL_ARGUMENT = -3,
    EX_NULL_POINTER = -4,
    EX_ILLEGAL_STATE = -5,
    EX_NETWORK_MAIN_THREAD = -6,
    EX_UNSUPPORTED_OPERATION = -7,
    EX_SERVICE_SPECIFIC = -8,
    EX_PARCELABLE = -9,

    /**
     * This is special, and indicates to native binder proxies that the
     * transaction has failed at a low level.
     */
    EX_TRANSACTION_FAILED = -129,
};

/**
 * One of the EXCEPTION_* types.
 *
 * All unrecognized values are coerced into EXCEPTION_TRANSACTION_FAILED.
 *
 * These exceptions values are used by the SDK for parcelables. Also see Parcel.java.
 */
typedef int32_t binder_exception_t;

/**
 * This is a helper class that encapsulates a standard way to keep track of and chain binder errors
 * along with service specific errors.
 *
 * It is not required to be used in order to parcel/receive transactions, but it is required in
 * order to be compatible with standard AIDL transactions since it is written as the header to the
 * out parcel for transactions which get executed (don't fail during unparceling of input arguments
 * or sooner).
 */
struct AStatus;
typedef struct AStatus AStatus;

/**
 * New status which is considered a success.
 *
 * Available since API level 29.
 *
 * \return a newly constructed status object that the caller owns.
 */
__attribute__((warn_unused_result)) AStatus* AStatus_newOk() __INTRODUCED_IN(29);

/**
 * New status with exception code.
 *
 * Available since API level 29.
 *
 * \param exception the code that this status should represent. If this is EX_NONE, then this
 * constructs an non-error status object.
 *
 * \return a newly constructed status object that the caller owns.
 */
__attribute__((warn_unused_result)) AStatus* AStatus_fromExceptionCode(binder_exception_t exception)
        __INTRODUCED_IN(29);

/**
 * New status with exception code and message.
 *
 * Available since API level 29.
 *
 * \param exception the code that this status should represent. If this is EX_NONE, then this
 * constructs an non-error status object.
 * \param message the error message to associate with this status object.
 *
 * \return a newly constructed status object that the caller owns.
 */
__attribute__((warn_unused_result)) AStatus* AStatus_fromExceptionCodeWithMessage(
        binder_exception_t exception, const char* message) __INTRODUCED_IN(29);

/**
 * New status with a service speciic error.
 *
 * This is considered to be EX_TRANSACTION_FAILED with extra information.
 *
 * Available since API level 29.
 *
 * \param serviceSpecific an implementation defined error code.
 *
 * \return a newly constructed status object that the caller owns.
 */
__attribute__((warn_unused_result)) AStatus* AStatus_fromServiceSpecificError(
        int32_t serviceSpecific) __INTRODUCED_IN(29);

/**
 * New status with a service specific error and message.
 *
 * This is considered to be EX_TRANSACTION_FAILED with extra information.
 *
 * Available since API level 29.
 *
 * \param serviceSpecific an implementation defined error code.
 * \param message the error message to associate with this status object.
 *
 * \return a newly constructed status object that the caller owns.
 */
__attribute__((warn_unused_result)) AStatus* AStatus_fromServiceSpecificErrorWithMessage(
        int32_t serviceSpecific, const char* message) __INTRODUCED_IN(29);

/**
 * New status with binder_status_t. This is typically for low level failures when a binder_status_t
 * is returned by an API on AIBinder or AParcel, and that is to be returned from a method returning
 * an AStatus instance. This is the least preferable way to return errors.
 * Prefer exceptions (particularly service-specific errors) when possible.
 *
 * Available since API level 29.
 *
 * \param status a low-level error to associate with this status object.
 *
 * \return a newly constructed status object that the caller owns.
 */
__attribute__((warn_unused_result)) AStatus* AStatus_fromStatus(binder_status_t status)
        __INTRODUCED_IN(29);

/**
 * Whether this object represents a successful transaction. If this function returns true, then
 * AStatus_getExceptionCode will return EX_NONE.
 *
 * Available since API level 29.
 *
 * \param status the status being queried.
 *
 * \return whether the status represents a successful transaction. For more details, see below.
 */
bool AStatus_isOk(const AStatus* status) __INTRODUCED_IN(29);

/**
 * The exception that this status object represents.
 *
 * Available since API level 29.
 *
 * \param status the status being queried.
 *
 * \return the exception code that this object represents.
 */
binder_exception_t AStatus_getExceptionCode(const AStatus* status) __INTRODUCED_IN(29);

/**
 * The service specific error if this object represents one. This function will only ever return a
 * non-zero result if AStatus_getExceptionCode returns EX_SERVICE_SPECIFIC. If this function returns
 * 0, the status object may still represent a different exception or status. To find out if this
 * transaction as a whole is okay, use AStatus_isOk instead.
 *
 * Available since API level 29.
 *
 * \param status the status being queried.
 *
 * \return the service-specific error code if the exception code is EX_SERVICE_SPECIFIC or 0.
 */
int32_t AStatus_getServiceSpecificError(const AStatus* status) __INTRODUCED_IN(29);

/**
 * The status if this object represents one. This function will only ever return a non-zero result
 * if AStatus_getExceptionCode returns EX_TRANSACTION_FAILED. If this function return 0, the status
 * object may represent a different exception or a service specific error. To find out if this
 * transaction as a whole is okay, use AStatus_isOk instead.
 *
 * Available since API level 29.
 *
 * \param status the status being queried.
 *
 * \return the status code if the exception code is EX_TRANSACTION_FAILED or 0.
 */
binder_status_t AStatus_getStatus(const AStatus* status) __INTRODUCED_IN(29);

/**
 * If there is a message associated with this status, this will return that message. If there is no
 * message, this will return an empty string.
 *
 * The returned string has the lifetime of the status object passed into this function.
 *
 * Available since API level 29.
 *
 * \param status the status being queried.
 *
 * \return the message associated with this error.
 */
const char* AStatus_getMessage(const AStatus* status) __INTRODUCED_IN(29);

/**
 * Get human-readable description for debugging.
 *
 * Available since API level 30.
 *
 * \param status the status being queried.
 *
 * \return a description, must be deleted with AStatus_deleteDescription.
 */
__attribute__((warn_unused_result)) const char* AStatus_getDescription(const AStatus* status)
        __INTRODUCED_IN(30);

/**
 * Delete description.
 *
 * \param description value from AStatus_getDescription
 */
void AStatus_deleteDescription(const char* description) __INTRODUCED_IN(30);

/**
 * Deletes memory associated with the status instance.
 *
 * Available since API level 29.
 *
 * \param status the status to delete, returned from AStatus_newOk or one of the AStatus_from* APIs.
 */
void AStatus_delete(AStatus* status) __INTRODUCED_IN(29);

__END_DECLS

/** @} */