/*
 * Copyright (c) 2024 Huawei Device Co., Ltd.
 * 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 AbilityBase
 * @{
 *
 * @brief Describe the functions of want.
 *
 * @syscap SystemCapability.Ability.AbilityBase
 * @since 15
 */

/**
 * @file want.h
 *
 * @brief Defines the want APIs.
 *
 * @library libability_base_want.so
 * @kit AbilityKit
 * @syscap SystemCapability.Ability.AbilityBase
 * @since 15
 */

#ifndef ABILITY_BASE_WANT_H
#define ABILITY_BASE_WANT_H

#include <stddef.h>
#include <stdint.h>
#include "ability_base_common.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Indicates information of element.
 *
 * @since 15
 */
typedef struct AbilityBase_Element {
    /** Indicates the name of application. */
    char* bundleName;
    /** Indicates the name of module. */
    char* moduleName;
    /** Indicates the name of ability. */
    char* abilityName;
} AbilityBase_Element;

struct AbilityBase_Want;
typedef struct AbilityBase_Want AbilityBase_Want;

/**
 * @brief Create want.
 *
 * @param element Information of element.
 * @return Returns the newly created AbilityBase_Want object.
 *
 * @since 15
 */
AbilityBase_Want* OH_AbilityBase_CreateWant(AbilityBase_Element element);

/**
 * @brief Destroy input want.
 *
 * @param want The want to be deleted.
 * @return The error code.
 *         {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful.
 *         {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the want is invalid.
 * @since 15
 */
AbilityBase_ErrorCode OH_AbilityBase_DestroyWant(AbilityBase_Want* want);

/**
 * @brief Set want element.
 *
 * @param want The want that needs to be set element.
 * @param element Information of element.
 * @return The error code.
 *         {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful.
 *         {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the want is invalid.
 * @since 15
 */
AbilityBase_ErrorCode OH_AbilityBase_SetWantElement(AbilityBase_Want* want, AbilityBase_Element element);

/**
 * @brief Get want element.
 *
 * @param want The want for the element that has been obtained.
 * @param element The element obtained from want.
 * @return The error code.
 *         {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful.
 *         {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the want or element is invalid.
 * @since 15
 */
AbilityBase_ErrorCode OH_AbilityBase_GetWantElement(AbilityBase_Want* want, AbilityBase_Element* element);

/**
 * @brief Set want char param.
 *
 * @param want The want needs to be set char param.
 * @param key The key of char param.
 * @param value The value of char param.
 * @return The error code.
 *         {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful.
 *         {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid.
 * @since 15
 */
AbilityBase_ErrorCode OH_AbilityBase_SetWantCharParam(AbilityBase_Want* want, const char* key, const char* value);

/**
 * @brief Get want char param.
 *
 * @param want The want for the char param that has been obtained.
 * @param key The key of char param.
 * @param value The value of char param.
 * @param valueSize Size of the value.
 * @return The error code.
 *         {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful.
 *         {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid.
 * @since 15
 */
AbilityBase_ErrorCode OH_AbilityBase_GetWantCharParam(AbilityBase_Want* want, const char* key,
    char* value, size_t valueSize);

/**
 * @brief Add fd to want.
 *
 * @param want The want needs to be add fd.
 * @param key The key of the fd.
 * @param fd File Descriptor.
 * @return The error code.
 *         {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful.
 *         {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid.
 * @since 15
 */
AbilityBase_ErrorCode OH_AbilityBase_AddWantFd(AbilityBase_Want* want, const char* key, int32_t fd);

/**
 * @brief Get fd from want.
 *
 * @param want The want that includes fd.
 * @param key The key of the fd.
 * @param fd File Descriptor.
 * @return The error code.
 *         {@link ABILITY_BASE_ERROR_CODE_NO_ERROR} if the operation is successful.
 *         {@link ABILITY_BASE_ERROR_CODE_PARAM_INVALID} if the input parameters are invalid.
 * @since 15
 */
AbilityBase_ErrorCode OH_AbilityBase_GetWantFd(AbilityBase_Want* want, const char* key, int32_t* fd);

#ifdef __cplusplus
} // extern "C"
#endif

/** @} */
#endif // ABILITY_BASE_WANT_H