include/display.h

   1 /*
   2  * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_SYSTEM_DISPLAY_H__
  19 #define __TIZEN_SYSTEM_DISPLAY_H__
  20
  21
  22 #include "device-error.h"
  23
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29
  30 /**
  31  * @addtogroup CAPI_SYSTEM_DEVICE_DISPLAY_MODULE
  32  * @{
  33  */
  34
  35
  36 /**
  37  * @brief Gets the number of display devices.
  38  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  39  * @privlevel public
  40  * @privilege %http://tizen.org/privilege/display
  41  * @param[out] device_number The total number of displays
  42  * @return @c 0 on success,
  43  *         otherwise a negative error value
  44  * @retval #DEVICE_ERROR_NONE Successful
  45  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  46  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  47  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  48  * @see device_display_get_brightness()
  49  * @see device_display_set_brightness()
  50  * @see device_display_get_max_brightness()
  51  */
  52 int device_display_get_numbers(int *device_number);
  53
  54
  55 /**
  56  * @brief Gets the maximum brightness value that can be set.
  57  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  58  * @privlevel public
  59  * @privilege %http://tizen.org/privilege/display
  60  * @param[in] display_index The index of the display \n
  61  *                          It can be greater than or equal to @c 0 and less than the number of displays returned by device_display_get_numbers(). \n
  62  *                          The index zero is always assigned to the main display
  63  * @param[out] max_brightness The maximum brightness value of the display
  64  * @return @c 0 on success,
  65  *         otherwise a negative error value
  66  * @retval #DEVICE_ERROR_NONE Successful
  67  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  68  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  69  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  70  * @see device_display_get_numbers()
  71  * @see device_display_set_brightness()
  72  * @see device_display_get_brightness()
  73  */
  74 int device_display_get_max_brightness(int display_index, int *max_brightness);
  75
  76
  77 /**
  78  * @brief Gets the display brightness value.
  79  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  80  * @privlevel public
  81  * @privilege %http://tizen.org/privilege/display
  82  * @param[in] display_index The index of the display \n
  83  *                          It can be greater than or equal to @c 0 and less than the number of displays returned by device_display_get_numbers(). \n
  84  *                          The index zero is always assigned to the main display
  85  * @param[out] brightness The current brightness value of the display
  86  * @return @c 0 on success,
  87  *         otherwise a negative error value
  88  * @retval #DEVICE_ERROR_NONE Successful
  89  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  90  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  91  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  92  * @see device_display_get_numbers()
  93  * @see device_display_set_brightness()
  94  * @see device_display_get_max_brightness()
  95  */
  96 int device_display_get_brightness(int display_index, int *brightness);
  97
  98
  99 /**
 100  * @brief Sets the display brightness value.
 101  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 102  * @privlevel public
 103  * @privilege %http://tizen.org/privilege/display
 104  * @param[in] display_index The index of the display \n
 105  *                          It can be greater than or equal to @c 0 and less than the number of displays returned by device_display_get_numbers(). \n
 106  *                          The index zero is always assigned to the main display
 107  * @param[in] brightness The new brightness value to set \n
 108  *                       The maximum value can be represented by device_display_get_max_brightness()
 109  * @return @c 0 on success,
 110  *         otherwise a negative error value
 111  * @retval #DEVICE_ERROR_NONE Successful
 112  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 113  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
 114  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 115  * @see device_display_get_numbers()
 116  * @see device_display_get_max_brightness()
 117  * @see device_display_get_brightness()
 118  */
 119 int device_display_set_brightness(int display_index, int brightness);
 120
 121
 122 /**
 123  * @brief Enumeration for the available display states.
 124  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 125  */
 126 typedef enum {
 127         DISPLAY_STATE_NORMAL, /**< Normal state */
 128         DISPLAY_STATE_SCREEN_DIM, /**< @if TV @internal @endif Screen dim state */
 129         DISPLAY_STATE_SCREEN_OFF, /**< Screen off state */
 130 } display_state_e;
 131
 132
 133 /**
 134  * @brief Gets the current display state.
 135  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 136  * @param[out] state The display state
 137  * @return @c 0 on success,
 138  *         otherwise a negative error value
 139  * @retval #DEVICE_ERROR_NONE Successful
 140  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 141  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 142  * @see device_add_callback
 143  * @see device_remove_callback
 144  * @see #DEVICE_CALLBACK_DISPLAY_STATE
 145  */
 146 int device_display_get_state(display_state_e *state);
 147
 148
 149 /**
 150  * @deprecated Deprecated Since @if WEARABLE 3.0 @else 2.4 @endif
 151  * @brief Changes the display state by force.
 152  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 153  * @privlevel public
 154  * @privilege %http://tizen.org/privilege/display
 155  * @remarks This API triggers display change process and then updates the status when it completes. While the operation is on-going, the device_display_get_state() function returns previous display state.
 156  * @param[in] state The display state
 157  * @return @c 0 on success,
 158  *         otherwise a negative error value
 159  * @retval #DEVICE_ERROR_NONE Successful
 160  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 161  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
 162  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 163  * @see device_power_request_lock()
 164  * @see device_power_release_lock()
 165  * @see device_add_callback
 166  * @see device_remove_callback
 167  * @see #DEVICE_CALLBACK_DISPLAY_STATE
 168  *
 169  * @par Example
 170  * @code
 171  *  ...
 172  *  result = device_display_change_state(DISPLAY_STATE_SCREEN_OFF);
 173  *  if (result < 0)
 174  *      dlog_print(DLOG_ERROR, LOG_TAG, "[ERROR] return value result =%d, \n",result);
 175  *  else
 176  *      dlog_print(DLOG_DEBUG, LOG_TAG, "[SUCCESS] return value result =%d \n",result);
 177  *  ...
 178  * @endcode
 179  */
 180 int device_display_change_state(display_state_e state) TIZEN_DEPRECATED_API;
 181
 182
 183 /**
 184  * @}
 185  */
 186
 187
 188 #ifdef __cplusplus
 189 }
 190 #endif
 191
 192
 193 #endif  // __TIZEN_SYSTEM_DISPLAY_H__