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 #include "device-error.h"
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27
  28 /**
  29  * @addtogroup CAPI_SYSTEM_DEVICE_DISPLAY_MODULE
  30  * @{
  31  */
  32
  33 /**
  34  * @brief Gets the number of display devices.
  35  *
  36  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  37  * @privlevel public
  38  * @privilege %http://tizen.org/privilege/display
  39  *
  40  * @param[out] device_number The total number of displays
  41  *
  42  * @return @c 0 on success,
  43  *         otherwise a negative error value
  44  *
  45  * @retval #DEVICE_ERROR_NONE               Successful
  46  * @retval #DEVICE_ERROR_INVALID_PARAMETER  Invalid parameter
  47  * @retval #DEVICE_ERROR_PERMISSION_DENIED  Permission denied
  48  * @retval #DEVICE_ERROR_OPERATION_FAILED   Operation failed
  49  *
  50  * @see device_display_get_brightness()
  51  * @see device_display_set_brightness()
  52  * @see device_display_get_max_brightness()
  53  */
  54 int device_display_get_numbers(int *device_number);
  55
  56 /**
  57  * @brief Gets the maximum brightness value that can be set.
  58  *
  59  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  60  * @privlevel public
  61  * @privilege %http://tizen.org/privilege/display
  62  *
  63  * @param[in] display_index     The index of the display \n
  64  *                              It can be greater than or equal to @c 0 and less than
  65  *                              the number of displays returned by device_display_get_numbers(). \n
  66  *                              The index zero is always assigned to the main display.
  67  * @param[out] max_brightness   The maximum brightness value of the display
  68  *
  69  * @return @c 0 on success,
  70  *         otherwise a negative error value
  71  *
  72  * @retval #DEVICE_ERROR_NONE               Successful
  73  * @retval #DEVICE_ERROR_INVALID_PARAMETER  Invalid parameter
  74  * @retval #DEVICE_ERROR_PERMISSION_DENIED  Permission denied
  75  * @retval #DEVICE_ERROR_OPERATION_FAILED   Operation failed
  76  *
  77  * @see device_display_get_numbers()
  78  * @see device_display_set_brightness()
  79  * @see device_display_get_brightness()
  80  */
  81 int device_display_get_max_brightness(int display_index, int *max_brightness);
  82
  83 /**
  84  * @brief Gets the display brightness value.
  85  *
  86  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  87  * @privlevel public
  88  * @privilege %http://tizen.org/privilege/display
  89  *
  90  * @param[in] display_index The index of the display \n
  91  *                          It can be greater than or equal to @c 0 and less than
  92  *                          the number of displays returned by device_display_get_numbers(). \n
  93  *                          The index zero is always assigned to the main display.
  94  * @param[out] brightness   The current brightness value of the display
  95  *
  96  * @return @c 0 on success,
  97  *         otherwise a negative error value
  98  *
  99  * @retval #DEVICE_ERROR_NONE               Successful
 100  * @retval #DEVICE_ERROR_INVALID_PARAMETER  Invalid parameter
 101  * @retval #DEVICE_ERROR_PERMISSION_DENIED  Permission denied
 102  * @retval #DEVICE_ERROR_OPERATION_FAILED   Operation failed
 103  *
 104  * @see device_display_get_numbers()
 105  * @see device_display_set_brightness()
 106  * @see device_display_get_max_brightness()
 107  */
 108 int device_display_get_brightness(int display_index, int *brightness);
 109
 110 /**
 111  * @brief Sets the display brightness value.
 112  *
 113  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 114  * @privlevel public
 115  * @privilege %http://tizen.org/privilege/display
 116  *
 117  * @param[in] display_index The index of the display \n
 118  *                          It can be greater than or equal to @c 0 and less than
 119  *                          the number of displays returned by device_display_get_numbers(). \n
 120  *                          The index zero is always assigned to the main display.
 121  * @param[in] brightness    The new brightness value to set \n
 122  *                          The maximum value can be represented by device_display_get_max_brightness().
 123  *
 124  * @return @c 0 on success,
 125  *         otherwise a negative error value
 126  *
 127  * @retval #DEVICE_ERROR_NONE               Successful
 128  * @retval #DEVICE_ERROR_INVALID_PARAMETER  Invalid parameter
 129  * @retval #DEVICE_ERROR_PERMISSION_DENIED  Permission denied
 130  * @retval #DEVICE_ERROR_OPERATION_FAILED   Operation failed
 131  *
 132  * @see device_display_get_numbers()
 133  * @see device_display_get_max_brightness()
 134  * @see device_display_get_brightness()
 135  */
 136 int device_display_set_brightness(int display_index, int brightness);
 137
 138 /**
 139  * @brief   Enumeration for the available display states.
 140  * @details An application cannot put the device into the power off state or the suspend state.
 141  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 142  */
 143 typedef enum
 144 {
 145     DISPLAY_STATE_NORMAL,      /**< Normal state */
 146     DISPLAY_STATE_SCREEN_DIM,  /**< Screen dim state */
 147     DISPLAY_STATE_SCREEN_OFF,  /**< Screen off state */
 148 } display_state_e;
 149
 150 /**
 151  * @brief Gets the current display state.
 152  *
 153  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 154  *
 155  * @param[out] state the display state
 156  *
 157  * @return @c 0 on success,
 158  *         otherwise a negative error value
 159  *
 160  * @retval #DEVICE_ERROR_NONE               Successful
 161  * @retval #DEVICE_ERROR_INVALID_PARAMETER  Invalid parameter
 162  * @retval #DEVICE_ERROR_OPERATION_FAILED   Operation failed
 163  *
 164  * @see device_add_callback
 165  * @see device_remove_callback
 166  * @see #DEVICE_CALLBACK_DISPLAY_STATE
 167  */
 168 int device_display_get_state(display_state_e *state);
 169
 170 /**
 171  * @deprecated Deprecated Since @if WEARABLE 3.0 @else 2.4 @endif
 172  * @brief Changes the display state by force.
 173  *
 174  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 175  * @privlevel public
 176  * @privilege %http://tizen.org/privilege/display
 177  *
 178  * @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
 179  *
 180  * @param[in] state the display state
 181  *
 182  * @return @c 0 on success,
 183  *         otherwise a negative error value
 184  *
 185  * @retval #DEVICE_ERROR_NONE               Successful
 186  * @retval #DEVICE_ERROR_INVALID_PARAMETER  Invalid parameter
 187  * @retval #DEVICE_ERROR_PERMISSION_DENIED  Permission denied
 188  * @retval #DEVICE_ERROR_OPERATION_FAILED   Operation failed
 189  *
 190  * @see device_power_request_lock()
 191  * @see device_power_release_lock()
 192  * @see device_add_callback
 193  * @see device_remove_callback
 194  * @see #DEVICE_CALLBACK_DISPLAY_STATE
 195  *
 196  * @par Example
 197  * @code
 198  *  ...
 199  *  result = device_display_change_state(DISPLAY_STATE_SCREEN_OFF);
 200  *  if( result < 0 )
 201  *      printf("[ERROR] return value result =%d, \n",result);
 202  *  else
 203  *      printf("[SUCCESS] return value result =%d \n",result);
 204  *  ...
 205  * @endcode
 206  */
 207 int device_display_change_state(display_state_e state);
 208
 209 /**
 210  * @}
 211  */
 212
 213 #ifdef __cplusplus
 214 }
 215 #endif
 216
 217 #endif  // __TIZEN_SYSTEM_DISPLAY_H__