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 #include "display-enum.h"
  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 2.3
  39  * @privlevel public
  40  * @privilege %http://tizen.org/privilege/display
  41  * @remarks #DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: %http://tizen.org/feature/display
  42  * @param[out] device_number The total number of displays
  43  * @return @c 0 on success,
  44  *         otherwise a negative error value
  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  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
  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 /**
  58  * @brief Gets the maximum brightness value that can be set.
  59  * @since_tizen 2.3
  60  * @privlevel public
  61  * @privilege %http://tizen.org/privilege/display
  62  * @remarks #DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: %http://tizen.org/feature/display \n
  63  *          or when the display HW module (e.g., plug-in touchscreen) is detached.
  64  * @param[in] display_index The index of the display \n
  65  *                          It can be greater than or equal to @c 0 and less than 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  * @return @c 0 on success,
  69  *         otherwise a negative error value
  70  * @retval #DEVICE_ERROR_NONE Successful
  71  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  72  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  73  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  74  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
  75  * @see device_display_get_numbers()
  76  * @see device_display_set_brightness()
  77  * @see device_display_get_brightness()
  78  */
  79 int device_display_get_max_brightness(int display_index, int *max_brightness);
  80
  81
  82 /**
  83  * @brief Gets the display brightness value.
  84  * @since_tizen 2.3
  85  * @privlevel public
  86  * @privilege %http://tizen.org/privilege/display
  87  * @remarks #DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: %http://tizen.org/feature/display \n
  88  *          or when the display HW module (e.g., plug-in touchscreen) is detached.
  89  * @param[in] display_index The index of the display \n
  90  *                          It can be greater than or equal to @c 0 and less than the number of displays returned by device_display_get_numbers(). \n
  91  *                          The index zero is always assigned to the main display
  92  * @param[out] brightness The current brightness value of the display
  93  * @return @c 0 on success,
  94  *         otherwise a negative error value
  95  * @retval #DEVICE_ERROR_NONE Successful
  96  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  97  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  98  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  99  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 100  * @see device_display_get_numbers()
 101  * @see device_display_set_brightness()
 102  * @see device_display_get_max_brightness()
 103  */
 104 int device_display_get_brightness(int display_index, int *brightness);
 105
 106
 107 /**
 108  * @brief Sets the display brightness value.
 109  * @since_tizen 2.3
 110  * @privlevel public
 111  * @privilege %http://tizen.org/privilege/display
 112  * @remarks #DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: %http://tizen.org/feature/display \n
 113  *          or when the display HW module (e.g., plug-in touchscreen) is detached.
 114  * @param[in] display_index The index of the display \n
 115  *                          It can be greater than or equal to @c 0 and less than the number of displays returned by device_display_get_numbers(). \n
 116  *                          The index zero is always assigned to the main display
 117  * @param[in] brightness The new brightness value to set \n
 118  *                       The maximum value can be represented by device_display_get_max_brightness()
 119  * @return @c 0 on success,
 120  *         otherwise a negative error value
 121  * @retval #DEVICE_ERROR_NONE Successful
 122  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 123  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
 124  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 125  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 126  * @see device_display_get_numbers()
 127  * @see device_display_get_max_brightness()
 128  * @see device_display_get_brightness()
 129  */
 130 int device_display_set_brightness(int display_index, int brightness);
 131
 132
 133 /**
 134  * @brief Gets the current display state.
 135  * @since_tizen 2.3
 136  * @remarks #DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: %http://tizen.org/feature/display
 137  * @param[out] state The display state
 138  * @return @c 0 on success,
 139  *         otherwise a negative error value
 140  * @retval #DEVICE_ERROR_NONE Successful
 141  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 142  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 143  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 144  * @see device_add_callback
 145  * @see device_remove_callback
 146  * @see #DEVICE_CALLBACK_DISPLAY_STATE
 147  */
 148 int device_display_get_state(display_state_e *state);
 149
 150
 151 /**
 152  * @brief Changes the display state by force.
 153  * @since_tizen 2.3
 154  * @privlevel public
 155  * @privilege %http://tizen.org/privilege/display
 156  * @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.
 157  * @remarks #DEVICE_ERROR_NOT_SUPPORTED is returned, when the following feature is not supported: %http://tizen.org/feature/display.state.
 158  * @param[in] state The display state
 159  * @return @c 0 on success,
 160  *         otherwise a negative error value
 161  * @retval #DEVICE_ERROR_NONE Successful
 162  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 163  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
 164  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 165  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 166  * @see device_power_request_lock()
 167  * @see device_power_release_lock()
 168  * @see device_add_callback
 169  * @see device_remove_callback
 170  * @see #DEVICE_CALLBACK_DISPLAY_STATE
 171  *
 172  * @par Example
 173  * @code
 174  *  ...
 175  *  result = device_display_change_state(DISPLAY_STATE_SCREEN_OFF);
 176  *  if (result < 0)
 177  *      dlog_print(DLOG_ERROR, LOG_TAG, "[ERROR] return value result =%d, \n",result);
 178  *  else
 179  *      dlog_print(DLOG_DEBUG, LOG_TAG, "[SUCCESS] return value result =%d \n",result);
 180  *  ...
 181  * @endcode
 182  */
 183 int device_display_change_state(display_state_e state);
 184
 185
 186 /**
 187  * @}
 188  */
 189
 190
 191 #ifdef __cplusplus
 192 }
 193 #endif
 194
 195
 196 #endif  // __TIZEN_SYSTEM_DISPLAY_H__