tizen 2.4 release
[framework/uifw/libeom.git] / include / eom.h
1 /**************************************************************************
2
3 External Output Manager (EOM)
4
5 Copyright 2014 Samsung Electronics co., Ltd. All Rights Reserved.
6
7 Contact:
8 SooChan Lim <sc1.lim@samsung.com>
9 Boram Park <boram1288.park@samsung.com>
10 Changyeon Lee <cyeon.lee@samsung.com>
11 JunKyeong Kim <jk0430.kim@samsung.com>
12
13 Permission is hereby granted, free of charge, to any person obtaining a
14 copy of this software and associated documentation files (the
15 "Software"), to deal in the Software without restriction, including
16 without limitation the rights to use, copy, modify, merge, publish,
17 distribute, sub license, and/or sell copies of the Software, and to
18 permit persons to whom the Software is furnished to do so, subject to
19 the following conditions:
20
21 The above copyright notice and this permission notice (including the
22 next paragraph) shall be included in all copies or substantial portions
23 of the Software.
24
25 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
26 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
27 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
28 IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
29 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
30 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
31 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
32
33 **************************************************************************/
34
35 #ifndef __EOM_H__
36 #define __EOM_H__
37
38 /**
39  * @addtogroup CAPI_UI_EOM_MODULE
40  * @{
41  */
42
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46
47 #include <stdint.h>
48 #include <stddef.h>
49 #include <stdbool.h>
50 #include <string.h>
51 #include <tizen.h>
52 #include <Elementary.h>
53
54 /**
55  * @file eom.h
56  */
57 #ifndef TIZEN_ERROR_EOM
58 #define TIZEN_ERROR_EOM                 -0x02F20000 | 0x00
59 #endif
60 /**
61  * @brief Enumeration of External Output Manager (EOM) error type
62  * @since_tizen 2.4
63  */
64 typedef enum {
65         EOM_ERROR_NONE = TIZEN_ERROR_NONE,                            /**< Success */
66         EOM_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,          /**< Memory allocation failure */
67         EOM_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,  /**< Invalid input parameter */
68         EOM_ERROR_NO_SUCH_DEVICE = TIZEN_ERROR_NO_SUCH_DEVICE,        /**< Invalid external output instance */
69         EOM_ERROR_CONNECTION_FAILURE = TIZEN_ERROR_EOM | 0x01,        /**< Connection failure */
70         EOM_ERROR_MESSAGE_SENDING_FAILURE = TIZEN_ERROR_EOM | 0x02,   /**< Message sending failure */
71         EOM_ERROR_MESSAGE_OPERATION_FAILURE = TIZEN_ERROR_EOM | 0x03, /**< Message operation failure */
72 } eom_error_e;
73
74 /**
75  * @brief Enumeration of external output type
76  * @since_tizen 2.4
77  */
78 typedef enum {
79         EOM_OUTPUT_TYPE_UNKNOWN,      /**< Unknown output type */
80         EOM_OUTPUT_TYPE_VGA,          /**< VGA output */
81         EOM_OUTPUT_TYPE_DVII,         /**< DVII output type */
82         EOM_OUTPUT_TYPE_DVID,         /**< DVID output type */
83         EOM_OUTPUT_TYPE_DVIA,         /**< DVIA output type */
84         EOM_OUTPUT_TYPE_COMPOSITE,    /**< Composite output type */
85         EOM_OUTPUT_TYPE_SVIDEO,       /**< SVIDEO output type */
86         EOM_OUTPUT_TYPE_LVDS,         /**< LVDS output type */
87         EOM_OUTPUT_TYPE_COMPONENT,    /**< Component output type */
88         EOM_OUTPUT_TYPE_9PINDIN,      /**< 9PinDIN output type */
89         EOM_OUTPUT_TYPE_DISPLAYPORT,  /**< DisplayPort output type */
90         EOM_OUTPUT_TYPE_HDMIA,        /**< HDMIA output type */
91         EOM_OUTPUT_TYPE_HDMIB,        /**< HDMIB output type */
92         EOM_OUTPUT_TYPE_TV,           /**< TV output type */
93         EOM_OUTPUT_TYPE_EDP,          /**< EDP output type */
94         EOM_OUTPUT_TYPE_VIRTUAL,      /**< VIRTUAL output type */
95         EOM_OUTPUT_TYPE_DSI,          /**< DSI output type */
96         EOM_OUTPUT_TYPE_MAX,
97 } eom_output_type_e;
98
99 /**
100  * @brief Enumeration of external output mode
101  * @since_tizen 2.4
102  */
103 typedef enum {
104         EOM_OUTPUT_MODE_NONE,          /**< None */
105         EOM_OUTPUT_MODE_MIRROR,        /**< Mirror mode */
106         EOM_OUTPUT_MODE_PRESENTATION,  /**< Presentation mode */
107         EOM_OUTPUT_MODE_MAX,
108 } eom_output_mode_e;
109
110 /**
111  * @brief Enumeration of External Output Manager (EOM) attributes
112  * @since_tizen 2.4
113  */
114 typedef enum {
115         EOM_OUTPUT_ATTRIBUTE_NONE,             /**< None */
116         EOM_OUTPUT_ATTRIBUTE_NORMAL,           /**< Normal presentation mode window showing on external output */
117         EOM_OUTPUT_ATTRIBUTE_EXCLUSIVE_SHARE,  /**< Exclusive share presentation mode window showing on external output */
118         EOM_OUTPUT_ATTRIBUTE_EXCLUSIVE,        /**< Exclusive presentation mode window showing on external output */
119         EOM_OUTPUT_ATTRIBUTE_MAX,
120 } eom_output_attribute_e;
121
122 /**
123  * @brief Enumeration of External Output Manager (EOM) attribute state
124  * @since_tizen 2.4
125  */
126 typedef enum {
127         EOM_OUTPUT_ATTRIBUTE_STATE_NONE,      /**< None */
128         EOM_OUTPUT_ATTRIBUTE_STATE_ACTIVE,    /**< Output attribute is active */
129         EOM_OUTPUT_ATTRIBUTE_STATE_INACTIVE,  /**< Output attribute is inactive */
130         EOM_OUTPUT_ATTRIBUTE_STATE_LOST,      /**< Cannot use external output */
131         EOM_OUTPUT_ATTRIBUTE_STATE_MAX,
132 } eom_output_attribute_state_e;
133
134 /**
135  * @brief Definition for external output ID
136  * @since_tizen 2.4
137  */
138 typedef unsigned int eom_output_id;
139
140 /**
141  * @brief Called when External Output Manager (EOM) module sends output connection notification.
142  * @since_tizen 2.4
143  * @param[in] output_id  The output id which is connected output
144  * @param[in] user_data  The pointer of user data which is passed to eom_output_added_cb function
145  * @see eom_set_output_added_cb()
146  * @see eom_unset_output_added_cb()
147  */
148 typedef void (*eom_output_added_cb)(eom_output_id output_id, void *user_data);
149
150 /**
151  * @brief Called when External Output Manager (EOM) module sends output disconnection notification.
152  * @since_tizen 2.4
153  * @param[in] output_id  The output id which is connected output
154  * @param[in] user_data  The pointer of user data which is passed to eom_output_removed_cb function
155  * @see eom_set_output_removed_cb()
156  * @see eom_unset_output_removed_cb()
157  */
158 typedef void (*eom_output_removed_cb)(eom_output_id output_id, void *user_data);
159
160 /**
161  * @brief Called when External Output Manager (EOM) module sends output mode changing notification.
162  * @since_tizen 2.4
163  * @param[in] output_id  The output id which is connected output
164  * @param[in] user_data  The pointer of user data which is passed to eom_mode_changed_cb function
165  * @see eom_set_mode_changed_cb()
166  * @see eom_unset_mode_changed_cb()
167  */
168 typedef void (*eom_mode_changed_cb)(eom_output_id output_id, void *user_data);
169
170 /**
171  * @brief Called when External Output Manager (EOM) module sends output attribute changing notification.
172  * @since_tizen 2.4
173  * @param[in] output_id  The output id which is connected output
174  * @param[in] user_data  The pointer of user data which is passed to eom_attribute_changed_cb function
175  * @see eom_set_attribute_changed_cb()
176  * @see eom_unset_attribute_changed_cb()
177  */
178 typedef void (*eom_attribute_changed_cb)(eom_output_id output_id, void *user_data);
179
180 /**
181  * @brief Initializes External Output Manager (EOM).
182  * @details User should call this function previously for using EOM.
183  * @since_tizen 2.4
184  * @remarks After all using, call eom_deinit() function for resource returning.
185  * @return 0 on success, otherwise a negative error value
186  * @retval #EOM_ERROR_NONE Successful
187  * @retval #EOM_ERROR_CONNECTION_FAILURE The EOM connection failure
188  * @see eom_deinit()
189  * @see #eom_error_e
190  */
191 int eom_init(void);
192
193 /**
194  * @brief Finalizes External Output Manager (EOM).
195  * @details User should call this function after using EOM to release all resources of EOM.
196  * @since_tizen 2.4
197  * @see eom_init()
198  */
199 void eom_deinit(void);
200
201 /**
202  * @brief Registers a callback function to get output connection notification from External Output Manager (EOM) module.
203  * @since_tizen 2.4
204  * @param[in] callback  The function pointer of eom_output_added_cb callback function
205  * @param[in] user_data  The pointer of user data which is passed to eom_output_added_cb function
206  * @return 0 on success, otherwise a negative error value
207  * @retval #EOM_ERROR_NONE Successful
208  * @retval #EOM_ERROR_OUT_OF_MEMORY Memory allocation failure
209  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
210  * @pre eom_init()
211  * @pre eom_get_eom_output_ids()
212  * @see eom_unset_output_added_cb()
213  * @see #eom_output_added_cb
214  */
215 int eom_set_output_added_cb(eom_output_added_cb callback, void *user_data);
216
217 /**
218  * @brief Unregisters the callback function.
219  * @since_tizen 2.4
220  * @param[in] callback  The function pointer of eom_output_added_cb callback function
221  * @return 0 on success, otherwise a negative error value
222  * @retval #EOM_ERROR_NONE Successful
223  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
224  * @pre eom_init()
225  * @pre eom_get_eom_output_ids()
226  * @see eom_set_output_added_cb()
227  * @see #eom_output_added_cb
228  */
229 int eom_unset_output_added_cb(eom_output_added_cb callback);
230
231 /**
232  * @brief Registers a callback function to get output disconnection notification from External Output Manager (EOM) module.
233  * @since_tizen 2.4
234  * @param[in] callback  The function pointer of eom_output_removed_cb callback function
235  * @param[in] user_data  The pointer of user data which is passed to eom_output_removed_cb function
236  * @return 0 on success, otherwise a negative error value
237  * @retval #EOM_ERROR_NONE Successful
238  * @retval #EOM_ERROR_OUT_OF_MEMORY Memory allocation failure
239  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
240  * @pre eom_init()
241  * @pre eom_get_eom_output_ids()
242  * @see eom_unset_output_removed_cb()
243  * @see #eom_output_removed_cb
244  */
245 int eom_set_output_removed_cb(eom_output_removed_cb callback, void *user_data);
246
247 /**
248  * @brief Unregisters the callback function.
249  * @since_tizen 2.4
250  * @param[in] callback  The function pointer of eom_output_removed_cb callback function
251  * @return 0 on success, otherwise a negative error value
252  * @retval #EOM_ERROR_NONE Successful
253  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
254  * @pre eom_init()
255  * @pre eom_get_eom_output_ids()
256  * @see eom_set_output_removed_cb()
257  * @see #eom_output_removed_cb
258  */
259 int eom_unset_output_removed_cb(eom_output_removed_cb callback);
260
261 /**
262  * @brief Registers a callback function to get output mode changing notification from External Output Manager (EOM) module.
263  * @since_tizen 2.4
264  * @param[in] callback  The function pointer of eom_mode_changed_cb callback function
265  * @param[in] user_data  The pointer of user data which is passed to eom_mode_changed_cb function
266  * @return 0 on success, otherwise a negative error value
267  * @retval #EOM_ERROR_NONE Successful
268  * @retval #EOM_ERROR_OUT_OF_MEMORY Memory allocation failure
269  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
270  * @pre eom_init()
271  * @pre eom_get_eom_output_ids()
272  * @see eom_unset_mode_changed_cb()
273  * @see #eom_mode_changed_cb
274  */
275 int eom_set_mode_changed_cb(eom_mode_changed_cb callback, void *user_data);
276
277 /**
278  * @brief Unregisters the callback function.
279  * @since_tizen 2.4
280  * @param[in] callback  The function pointer of eom_mode_changed_cb callback function
281  * @return 0 on success, otherwise a negative error value
282  * @retval #EOM_ERROR_NONE Successful
283  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
284  * @pre eom_init()
285  * @pre eom_get_eom_output_ids()
286  * @see eom_set_mode_changed_cb()
287  * @see #eom_mode_changed_cb
288  */
289 int eom_unset_mode_changed_cb(eom_mode_changed_cb callback);
290
291 /**
292  * @brief Registers a callback function to get output attribute changing notification from External Output Manager (EOM) module.
293  * @since_tizen 2.4
294  * @param[in] callback  The function pointer of eom_attribute_changed_cb callback function
295  * @param[in] user_data  The pointer of user data which is passed to eom_attribute_changed_cb function
296  * @return 0 on success, otherwise a negative error value
297  * @retval #EOM_ERROR_NONE Successful
298  * @retval #EOM_ERROR_OUT_OF_MEMORY Memory allocation failure
299  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
300  * @pre eom_init()
301  * @pre eom_get_eom_output_ids()
302  * @see eom_unset_attribute_changed_cb()
303  * @see #eom_attribute_changed_cb
304  */
305 int eom_set_attribute_changed_cb(eom_attribute_changed_cb callback, void *user_data);
306
307 /**
308  * @brief Unregisters the callback function.
309  * @since_tizen 2.4
310  * @param[in] callback  The function pointer of eom_attribute_changed_cb callback function
311  * @return 0 on success, otherwise a negative error value
312  * @retval #EOM_ERROR_NONE Successful
313  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
314  * @pre eom_init()
315  * @pre eom_get_eom_output_ids()
316  * @see eom_set_attribute_changed_cb()
317  * @see #eom_attribute_changed_cb
318  */
319 int eom_unset_attribute_changed_cb(eom_attribute_changed_cb callback);
320
321 /**
322  * @brief Gets the IDs and count of external output.
323  * @details This function returns the IDs of external output which are available to connect
324  * to target device, and the count of them also. User can get the id of external output
325  * which user want to watch.
326  * @since_tizen 2.4
327  * @remarks User should free return value by using free().\n
328  * The specific error code can be obtained using the get_last_result() method.
329  * Error codes are described in Exception section.
330  * @param[out] count  The count of the eom_output_id supported by system
331  * @return The array of the eom_output_id if this function succeeds, otherwise NULL
332  * @retval The pointer of #eom_output_id
333  * @exception #EOM_ERROR_NONE Successful
334  * @exception #EOM_ERROR_INVALID_PARAMETER Invalid parameter
335  * @exception #EOM_ERROR_OUT_OF_MEMORY Memory allocation failure
336  * @pre eom_init()
337  * @see #eom_output_id
338  * @see #eom_error_e
339  */
340 eom_output_id *eom_get_eom_output_ids(int *count);
341
342 /**
343  * @brief Gets type of external output.
344  * @since_tizen 2.4
345  * @remarks The specific error code can be obtained using the get_last_result()
346  * method. Error codes are described in Exception section.
347  * @param[in] output_id  The id of external output device
348  * @param[out] type  The type of external output instance
349  * @return 0 on success, otherwise a negative error value
350  * @retval #EOM_ERROR_NONE Successful
351  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
352  * @pre eom_init()
353  * @pre eom_get_eom_output_ids()
354  * @see #eom_output_id
355  * @see #eom_error_e
356  * @see #eom_output_type_e
357  */
358 int eom_get_output_type(eom_output_id output_id, eom_output_type_e *type);
359
360 /**
361  * @brief Gets mode of external output.
362  * @since_tizen 2.4
363  * @remarks The specific error code can be obtained using the get_last_result()
364  * method. Error codes are described in Exception section.
365  * @param[in] output_id  The id of external output device
366  * @param[out] mode  The mode of external output instance
367  * @return 0 on success, otherwise a negative error value
368  * @retval #EOM_ERROR_NONE Successful
369  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
370  * @retval #EOM_ERROR_NO_SUCH_DEVICE Invalid external output instance
371  * @pre eom_init()
372  * @pre eom_get_eom_output_ids()
373  * @see #eom_output_id
374  * @see #eom_error_e
375  * @see #eom_output_mode_e
376  */
377 int eom_get_output_mode(eom_output_id output_id, eom_output_mode_e *mode);
378
379 /**
380  * @brief Gets attribute of external output.
381  * @since_tizen 2.4
382  * @remarks The specific error code can be obtained using the get_last_result()
383  * method. Error codes are described in Exception section.
384  * @param[in] output_id  The id of external output device
385  * @param[out] attribute  The attribute of external output instance
386  * @return 0 on success, otherwise a negative error value
387  * @retval #EOM_ERROR_NONE Successful
388  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
389  * @retval #EOM_ERROR_NO_SUCH_DEVICE Invalid external output instance
390  * @pre eom_init()
391  * @pre eom_get_eom_output_ids()
392  * @see #eom_output_id
393  * @see #eom_error_e
394  * @see #eom_output_attribute_e
395  */
396 int eom_get_output_attribute(eom_output_id output_id, eom_output_attribute_e *attribute);
397
398 /**
399  * @brief Gets attribute state of external output.
400  * @since_tizen 2.4
401  * @remarks The specific error code can be obtained using the get_last_result()
402  * method. Error codes are described in Exception section.
403  * @param[in] output_id  The id of external output device
404  * @param[out] state  The attribute state of external output instance
405  * @return 0 on success, otherwise a negative error value
406  * @retval #EOM_ERROR_NONE Successful
407  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
408  * @retval #EOM_ERROR_NO_SUCH_DEVICE Invalid external output instance
409  * @pre eom_init()
410  * @pre eom_get_eom_output_ids()
411  * @see #eom_output_id
412  * @see #eom_error_e
413  * @see #eom_output_attribute_state_e
414  */
415 int eom_get_output_attribute_state(eom_output_id output_id, eom_output_attribute_state_e *state);
416
417 /**
418  * @brief Gets resolution of external output.
419  * @since_tizen 2.4
420  * @param[in] output_id  The id of external output device
421  * @param[out] width  The width of external output instance
422  * @param[out] height  The height of external output instance
423  * @return 0 on success, otherwise a negative error value
424  * @retval #EOM_ERROR_NONE Successful
425  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
426  * @retval #EOM_ERROR_NO_SUCH_DEVICE Invalid external output instance
427  * @pre eom_init()
428  * @pre eom_get_eom_output_ids()
429  * @see #eom_output_id
430  * @see #eom_error_e
431  */
432 int eom_get_output_resolution(eom_output_id output_id, int *width, int *height);
433
434 /**
435  * @brief Gets physical width/height (millimeters) of external output.
436  * @since_tizen 2.4
437  * @param[in] output_id  The id of external output device
438  * @param[out] phy_width  The physical mm width of external output instance
439  * @param[out] phy_height  The physical mm height of external output instance
440  * @return 0 on success, otherwise a negative error value
441  * @retval #EOM_ERROR_NONE Successful
442  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
443  * @retval #EOM_ERROR_NO_SUCH_DEVICE Invalid external output instance
444  * @pre eom_init()
445  * @pre eom_get_eom_output_ids()
446  * @see #eom_output_id
447  * @see #eom_error_e
448  */
449 int eom_get_output_physical_size(eom_output_id output_id, int *phy_width, int *phy_height);
450
451 /**
452  * @brief Sets the attribute of the external output ID.
453  * @details The application can set the External Output Manager (EOM) attribute to the external output ID.
454  * The EOM module manages the windows to display on external output and
455  * control the policy of external output. The application can recognize
456  * the attribute state and manage the resources when the application receives
457  * several notification callback from EOM module.
458  * @since_tizen 2.4
459  * @param[in] output_id  The id of external output device
460  * @param[in] attr  The attribute of the external output
461  * @return 0 on success, otherwise a negative error value
462  * @retval #EOM_ERROR_NONE Successful
463  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
464  * @retval #EOM_ERROR_NO_SUCH_DEVICE Invalid external output instance
465  * @retval #EOM_ERROR_MESSAGE_SENDING_FAILURE Communication failure with EOM module
466  * @retval #EOM_ERROR_MESSAGE_OPERATION_FAILURE Operation failure
467  * @pre eom_init()
468  * @pre eom_get_eom_output_ids()
469  * @see #eom_output_id
470  * @see #eom_error_e
471  */
472 int eom_set_output_attribute(eom_output_id output_id, eom_output_attribute_e attr);
473
474 /**
475  * @brief Sets window to the external output best resolution of external output device.
476  * @since_tizen 2.4
477  * @param[in] output_id  The id of external output device
478  * @param[in] win  The pointer of evas object
479  * @return 0 on success, otherwise a negative error value
480  * @retval #EOM_ERROR_NONE Successful
481  * @retval #EOM_ERROR_INVALID_PARAMETER Invalid parameter
482  * @retval #EOM_ERROR_NO_SUCH_DEVICE Invalid external output instance
483  * @retval #EOM_ERROR_MESSAGE_SENDING_FAILURE Communication failure with EOM module
484  * @retval #EOM_ERROR_MESSAGE_OPERATION_FAILURE Operation failure
485  * @pre eom_init()
486  * @pre eom_get_eom_output_ids()
487  * @see #eom_output_id
488  * @see #eom_error_e
489  */
490 int eom_set_output_window(eom_output_id output_id, Evas_Object *win);
491
492 #ifdef __cplusplus
493 }
494 #endif
495
496 /**
497 * @}
498 */
499
500 #endif /* __EOM_H__ */