roaming.h

/*
 * Copyright (c) 2000-2017 Samsung Electronics Co., Ltd All Rights Reserved
 *
 * PROPRIETARY/CONFIDENTIAL
 *
 * This software is the confidential and proprietary information of
 * SAMSUNG ELECTRONICS ("Confidential Information").
 * You shall not disclose such Confidential Information and shall
 * use it only in accordance with the terms of the license agreement
 * you entered into with SAMSUNG ELECTRONICS.
 * SAMSUNG make no representations or warranties about the suitability
 * of the software, either express or implied, including but not
 * limited to the implied warranties of merchantability, fitness for
 * a particular purpose, or non-infringement.
 * SAMSUNG shall not be liable for any damages suffered by licensee as
 * a result of using, modifying or distributing this software or its derivatives.
 */

#ifndef LIBMDM_MDM_ROAMING_H
#define LIBMDM_MDM_ROAMING_H

#include "mdm_client_type.h"

#ifdef __cplusplus
extern "C" {
#endif

MDM_DEPRECATED_API mdm_status_t mdm_get_allow_roaming_data(void);

MDM_DEPRECATED_API mdm_result_t mdm_set_allow_roaming_data(mdm_status_t n_status);


/*
 * @brief API to check whether cellular data usage during roaming is allowed or not for a specific SIM (based on slot
 ID).
 *
 * @since_mdm 1.1.0
 *
 * @since_tizen 2.3.2.3
 *
 * @feature %http://developer.samsung.com/tizen/feature/mdm
 *
 * @par Usage:
 * Admin can use this to check if cellular data usage during roaming is
 * enabled or not, and take appropriate action based on enterprise policy.
 *
 * @code{.c}
    mdm_status_t status = MDM_ALLOWED;

    // Get SIM card slot ID
    mdm_data_t *result = mdm_msim_get_sim_ids();
    GList *list = (GList *)result -> data;

    GList *item = g_list_first(list);
    char *sim_id_0 = g_strdup((char *)(item -> data));

    status = mdm_msim_get_allow_roaming_data(sim_id_0);
    if (status != MDM_STATUS_ERROR) {
          if (status == MDM_ALLOWED) {
             //ALLOWED
          } else if (status == MDM_RESTRICTED) {
            //RESTRICTED
          }
    } else {
          //ERROR: fail to get the status.
    }
 *
 * @endcode
 *
 * @param[in] id        SIM card id
 *
 * @return #mdm_status_t : The current prevention status.
 *
 * @retval #MDM_ALLOWED         Cellular data during roaming is allowed.
 * @retval #MDM_RESTRICTED      Cellular data during roaming is restricted.
 * @retval #MDM_STATUS_ERROR    Failure.
 *
 * @see mdm_msim_set_allow_roaming_data
 *
 */
mdm_status_t mdm_msim_get_allow_roaming_data(const char *id);

/*
 * @brief API to allow or restrict cellular data usage during roaming for
 * specific SIM (based on slot ID).
 *
 * @since_mdm 1.1.0
 *
 * @since_tizen 2.3.2.3
 *
 * @feature %http://developer.samsung.com/tizen/feature/mdm
 *
 * @par Usage:
 * An administrator can use this API to allow or restrict cellular data usage during roaming.
 * Disabling prevents applications from connecting to the Internet while the device is in roaming mode.
 * This setting is applied only when the device is in roaming mode.
 * If the status is set to restricted, the user cannot change this setting because the corresponding UI will be
 disabled.
 * If the status is set to allowed, the corresponding UI for this setting is enabled and the user can change it.
 *
 * @code{.c}
    mdm_result_t ret = MDM_RESULT_SUCCESS;
    mdm_status_t n_status = MDM_RESTRICTED;

    // Get SIM card slot ID
    mdm_data_t *result = mdm_msim_get_sim_ids();
    GList *list = (GList *)result -> data;

    GList *item = g_list_first(list);
    char *sim_id_0 = g_strdup((char *)(item -> data));

    ret = mdm_msim_set_allow_roaming_data(sim_id_0, n_status);
    if (ret != MDM_RESULT_SUCCESS) {
        //Fail
    } else {
        //Success
    }
 *
 * @endcode
 *
 * @privlevel public
 * @privilege %http://developer.samsung.com/tizen/privilege/mdm.roaming
 *
 * @param[in] id        SIM card id
 * @param[in] n_status  #MDM_RESTRICTED: Restricts the user from changing this setting and turns off cellular data during
 roaming.
 *                   \n #MDM_ALLOWED: Allows the user to change this setting. Cellular data must be turned on manually.
 *
 * @return #mdm_result_t : MDM_RESULT_SUCCESS on success, an error code on error
 *
 * @retval #MDM_RESULT_SUCCESS Successful
 * @retval #MDM_RESULT_FAIL General failure
 * @retval #MDM_RESULT_NOT_SUPPORTED Not supported
 * @retval #MDM_RESULT_INVALID_PARAM Invalid parameter
 * @retval #MDM_RESULT_ACCESS_DENIED The application does not have the privilege to call this function.
 *
 * @par Permission:
 * Usage of this API is restricted to registered clients only.
 *
 * @see mdm_msim_get_allow_roaming_data
 *
 */
mdm_result_t mdm_msim_set_allow_roaming_data(const char *id, const mdm_status_t n_status);

/*
 * @brief API to allow or restrict cellular data usage while roaming.
 *
 * @since_mdm 2.2.0
 *
 * @since_tizen 3.0.0.1
 *
 * @feature %http://developer.samsung.com/tizen/feature/mdm
 *
 * @par Usage:
 * The admin can use this API to allow or restrict cellular data usage for the end user while roaming.
 * Disabling roaming mode prevents applications from connecting to the Internet.
 *
 * @remark
 * Restriction of roaming change #mdm_status_t is written to #MDM_POLICY_ON_DATA_ROAMING_CHANGE notification file.
 * You can register a callback for this event using #mdm_register_policy_receiver.
 *
 * @code{.c}
    mdm_result_t result = knox_mdm_set_allow_data_roaming_change("SIM1", MDM_RESTRICTED);
    if(result == MDM_RESULT_SUCCESS) {
        // Success
        ...
    } else {
        // Error
        ...
    }
 * @endcode
 *
 * @privlevel public
 * @privilege %http://developer.samsung.com/tizen/privilege/mdm.roaming
 *
 * @param[in] simid     SIM identifier
 * @param[in] status    #MDM_RESTRICTED — The end user is restricted from changing the roaming setting and turns off
 cellular data during roaming.
 *                   \n #MDM_ALLOWED — The end user is allowed to change the roaming setting. Cellular data must be turned on
 manually.
 *
 * @return #mdm_result_t : MDM_RESULT_SUCCESS on success, an error code on error
 *
 * @retval MDM_RESULT_SUCCESS Successful
 * @retval MDM_RESULT_FAIL General failure
 * @retval MDM_RESULT_NOT_SUPPORTED Not supported
 * @retval MDM_RESULT_INVALID_PARAM Invalid parameter
 * @retval MDM_RESULT_ACCESS_DENIED The application does not have the privilege to call this function.
 *
 * @see knox_mdm_get_allow_roaming_data_change
 */
mdm_result_t knox_mdm_set_allow_roaming_data_change(const char *id, const mdm_status_t status);

/*
 * @brief API to check if the end user is allowed to use mobile data while roaming.
 *
 * @since_mdm 2.2.0
 *
 * @since_tizen 3.0.0.1
 *
 * @feature %http://developer.samsung.com/tizen/feature/mdm
 *
 * @par Usage:
 * Use this API to check if the end user is allowed to use mobile data while roaming, and take the appropriate action
 based on enterprise policy.
 *
 * @code{.c}
    mdm_status_t status = knox_mdm_get_allow_data_roaming_change("SIM1");
    if(result == MDM_RESTRICTED) {
        // Changes are blocked
        ...
    } else if(result == MDM_ALLOWED) {
        // Changes are allowed
        ...
    }
    else
    {
        // ERROR
        ...
    }
 * @endcode
 *
 * @return #mdm_status_t : The current prevention status.
 * @retval #MDM_RESTRICTED      The end user is restricted from using mobile data while roaming.
 * @retval #MDM_ALLOWED         The end user is allowed to use mobile data while roaming.
 * @retval #MDM_STATUS_ERROR    On any error.
 *
 * @see knox_mdm_set_allow_roaming_data_change
 */
mdm_status_t knox_mdm_get_allow_roaming_data_change(const char *id);

/* --------------------------------------------------------------------------------------------------------
 *                                        HIDDEN DOCUMENTATION
 * --------------------------------------------------------------------------------------------------------
 *
 * Hidden documentation won't be generated by doxygen unless
 * ROAMING_HIDDEN_API section is added to the ENABLED_SECTIONS
 * in the Doxygen configuration file.
 */

/*
 * @brief API to check whether automatic syncing during roaming is allowed or not.
 *
 * @since_mdm 1.1.0
 *
 * @since_tizen 2.3.2.3
 *
 * @feature %http://developer.samsung.com/tizen/feature/mdm
 *
 * @par Usage:
 * Admin can use this to check if the automatic sync of applications is
 * allowed or not, and take appropriate action based on enterprise policy.
 *
 * @code{.c}
    mdm_status_t status = MDM_ALLOWED;

    // Get SIM card slot ID
    mdm_data_t *result = mdm_msim_get_sim_ids();
    GList *list = (GList *)result -> data;

    GList *item = g_list_first(list);
    char *sim_id_0 = g_strdup((char *)(item -> data));

    status = mdm_msim_get_allow_roaming_sync(sim_id_0);
    if (status != MDM_STATUS_ERROR) {
          if (status == MDM_ALLOWED) {
            //ALLOWED
          } else if (status == MDM_RESTRICTED) {
            //RESTRICTED
          }
    } else {
          //ERROR: fail to get the status.
    }
 *
 * @endcode
 *
 * @param[in] id          SIM card id
 *
 * @return #mdm_status_t : The current prevention status.
 *
 * @retval #MDM_ALLOWED         Automatic sync during roaming is allowed.
 * @retval #MDM_RESTRICTED      Automatic sync during roaming is restricted.
 * @retval #MDM_STATUS_ERROR    Failure.
 *
 * @see mdm_msim_set_allow_roaming_sync
 *
 */
mdm_status_t mdm_msim_get_allow_roaming_sync(const char *id);

/*
 * @brief API to check whether processing of WAP PUSH messages during roaming is allowed or not.
 *
 * @since_mdm 1.1.0
 *
 * @since_tizen 2.3.2.3
 *
 * @feature %http://developer.samsung.com/tizen/feature/mdm
 *
 * @par Usage:
 * Admin can use this to check if processing of WAP PUSH messages during roaming is
 * enabled or not, and take appropriate action based on enterprise policy.
 *
 * @code{.c}
    mdm_status_t status = MDM_ALLOWED;

    // Get SIM card slot ID
    mdm_data_t *result = mdm_msim_get_sim_ids();
    GList *list = (GList *)result -> data;

    GList *item = g_list_first(list);
    char *sim_id_0 = g_strdup((char *)(item -> data));

    status = mdm_msim_get_allow_roaming_push(sim_id_0);
    if (status != MDM_STATUS_ERROR) {
          if (status == MDM_ALLOWED) {
             //ALLOWED
          } else if (status == MDM_RESTRICTED) {
            //RESTRICTED
          }
    } else {
          //ERROR: fail to get the status.
    }
 *
 * @endcode
 *
 * @param[in] id          SIM card id
 *
 * @return #mdm_status_t : The current prevention status.
 *
 * @retval #MDM_ALLOWED         Processing of WAP PUSH messages during roaming is allowed.
 * @retval #MDM_RESTRICTED      Processing of WAP PUSH messages during roaming is restricted.
 * @retval #MDM_STATUS_ERROR    Failure.
 *
 * @see mdm_msim_set_allow_roaming_push
 *
 */
mdm_status_t mdm_msim_get_allow_roaming_push(const char *id);

/*
 * @brief API to allow or restrict automatic application sync during roaming.
 *
 * @since_mdm 1.1.0
 *
 * @since_tizen 2.3.2.3
 *
 * @feature %http://developer.samsung.com/tizen/feature/mdm
 *
 * @par Usage:
 * An administrator can use this API to allow or restrict the automatic sync of applications such as
 * email, gmail, contacts, calendar, and other application that requires the usage of an account.
 * This setting is applied only when the device is in roaming mode.
 * If the status is set to restricted, the user cannot change this setting because the corresponding UI will be
 disabled.
 * If the status is set to allowed, the corresponding UI for this setting is enabled and the user can change it.
 *
 * @remark
 * Roaming sync restriction #mdm_status_t is written to #MDM_POLICY_ON_ROAMING_SYNC notification file.
 * You can register a callback for this event using #mdm_register_policy_receiver.
 *
 * @code{.c}
    mdm_result_t ret = MDM_RESULT_SUCCESS;
    mdm_status_t n_status = MDM_RESTRICTED;

    // Get SIM card slot ID
    mdm_data_t *result = mdm_msim_get_sim_ids();
    GList *list = (GList *)result -> data;

    GList *item = g_list_first(list);
    char *sim_id_0 = g_strdup((char *)(item -> data));

    ret = mdm_msim_set_allow_roaming_sync(sim_id_0, n_status);
    if (ret != MDM_RESULT_SUCCESS) {
        //Fail
    } else {
        //Success
    }
 *
 * @endcode
 *
 * @privlevel public
 * @privilege %http://developer.samsung.com/tizen/privilege/mdm.roaming
 *
 * @param[in] id        SIM card id
 * @param[in] n_status  #MDM_RESTRICTED: Restricts the user from changing this setting and turns off automatic sync
 during roaming.
 *                   \n #MDM_ALLOWED: Allows the user to change this setting. Cellular data must be turn on manually.
 *
 * @return #mdm_result_t : MDM_RESULT_SUCCESS on success, an error code on error
 *
 * @retval #MDM_RESULT_SUCCESS Successful
 * @retval #MDM_RESULT_FAIL General failure
 * @retval #MDM_RESULT_NOT_SUPPORTED Not supported
 * @retval #MDM_RESULT_INVALID_PARAM Invalid parameter
 * @retval #MDM_RESULT_ACCESS_DENIED The application does not have the privilege to call this function.
 *
 * @par Permission:
 * Usage of this API is restricted to registered clients only.
 *
 * @see mdm_msim_get_allow_roaming_sync
 *
 */
mdm_result_t mdm_msim_set_allow_roaming_sync(const char *id, const mdm_status_t n_status);

/*
 * @brief API to allow or restrict processing of WAP Push messages during roaming.
 *
 * @since_mdm 1.1.0
 *
 * @since_tizen 2.3.2.3
 *
 * @feature %http://developer.samsung.com/tizen/feature/mdm
 *
 * @par Usage:
 * An administrator can use this API to allow or restrict processing of WAP PUSH messages.
 * Restricting this setting prevents MMS messages from being received during roaming.
 * This setting is applied only when the device is in roaming mode.
 * If the status is set to restricted, the user cannot change this setting because the corresponding UI will be
 disabled.
 * If the status is set to allowed, the corresponding UI for this setting is enabled and the user can change it.
 *
 * @remark
 * Roaming push restriction #mdm_status_t is written to #MDM_POLICY_ON_ROAMING_PUSH notification file.
 * You can register a callback for this event using #mdm_register_policy_receiver.
 *
 * @code{.c}
    mdm_result_t ret = MDM_RESULT_SUCCESS;
    mdm_status_t n_status = MDM_RESTRICTED;

    // Get SIM card slot ID
    mdm_data_t *result = mdm_msim_get_sim_ids();
    GList *list = (GList *)result -> data;

    GList *item = g_list_first(list);
    char *sim_id_0 = g_strdup((char *)(item -> data));

    ret = mdm_msim_set_allow_roaming_push(sim_id_0, n_status);
    if (ret != MDM_RESULT_SUCCESS) {
        //Fail
    } else {
        //Success
    }
 *
 * @endcode
 *
 * @privlevel public
 * @privilege %http://developer.samsung.com/tizen/privilege/mdm.roaming
 *
 * @param[in] id        SIM card id
 * @param[in] n_status  #MDM_RESTRICTED: Restricts the user from changing this setting and disables the processing of WAP
 Push messages during roaming.
 *                   \n #MDM_ALLOWED: Allows the user to change this setting. Enabling the processing of WAP Push
 messages must be performed manually.
 *
 * @return #mdm_result_t : MDM_RESULT_SUCCESS on success, an error code on error
 *
 * @retval #MDM_RESULT_SUCCESS Successful
 * @retval #MDM_RESULT_FAIL General failure
 * @retval #MDM_RESULT_NOT_SUPPORTED Not supported
 * @retval #MDM_RESULT_INVALID_PARAM Invalid parameter
 * @retval #MDM_RESULT_ACCESS_DENIED The application does not have the privilege to call this function.
 *
 * @par Permission:
 * Usage of this API is restricted to registered clients only.
 *
 * @see mdm_msim_get_allow_roaming_push
 *
 */
mdm_result_t mdm_msim_set_allow_roaming_push(const char *id, const mdm_status_t n_status);

/* -----------------------------------------------------------------------------------------------------------------
 * END OF HIDDEN DOCUMENTATION
 * -----------------------------------------------------------------------------------------------------------------
 */

#ifdef __cplusplus
}
#endif

#endif //LIBMDM_MDM_ROAMING_H