/*
 * Copyright (c) 2018 Samsung Electronics Co., Ltd.
 *
 * Licensed under the Flora License, Version 1.1 (the License);
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://floralicense.org/license/
 *
 * 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.
 */

#ifndef __APPINFO_PROVIDER_H_
#define __APPINFO_PROVIDER_H_

#include <stdbool.h>

/**
 * @brief Iterator used to obtain all running apps.
 */
typedef struct app_info_iterator app_info_iterator_t;

/**
 * @brief Go to next element of iterator.
 * @param[in] iter Iterator struct.
 */
bool app_info_iterator_next(app_info_iterator_t *iter);

/**
 * @brief Gets app id from iterator.
 * @param[in] iter Iterator struct.
 */
const char *app_info_iterator_get_app_id(app_info_iterator_t *iter);

/**
 * @brief Gets pid of app from iterator.
 * @param[in] iter Iterator struct.
 */
int app_info_iterator_get_pid(app_info_iterator_t *iter);

/**
 * @brief Gets total number of apps in iterator
 * @param[in] iter Iterator struct.
 *
 * @return number of apps.
 */
int app_info_iterator_get_count(app_info_iterator_t *iter);

/**
 * @brief Frees resource used by iterator.
 * @param[in] iter Iterator struct.
 */
void app_info_iterator_free(app_info_iterator_t *iter);

/**
 * @brief Returns list of running Tizen applications.
 *
 * @return app_info_iterator, NULL when no apps are running or on error.
 *
 * @remark function is thread safe
 * @remark returned value should be released with @app_info_iterator_free
 */
app_info_iterator_t *app_info_provider_get_running_applications();

/**
 * @brief Searches Tizen applications main process id.
 *
 * @return pid (>0) on success, -1 if app_id was not found
 *
 * @remark function is thread safe
 * @remark app_provide_init should be called beforehead
 */
int app_info_provider_find_main_pid(const char *app_id);

/**
 * @brief Searches for Tizen application app_id with given pid.
 *
 * @return app_id, NULL on if pid was not found or not owned by any Tizen application
 *
 * @remark function is thread safe
 * @remark app_provide_init should be called beforehead
 * @remark the returned value should be released with @free
 */
char *app_info_provider_find_app_id(int pid);

/**
 * @brief Initializes app provider internals
 *
 * @return 0 on success, other value on error.
 */
int app_provider_init();

/**
 * @brief Shutdowns app provider internals
 */
void app_provider_shutdown();

#endif