include/mdg.h

   1 /*
   2  * Network Configuration Module
   3  *
   4  * Copyright (c) 2017 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19 #ifndef __TIZEN_NETWORK_MULTI_DEVICE_GROUP_MDG_H__
  20 #define __TIZEN_NETWORK_MULTI_DEVICE_GROUP_MDG_H__
  21
  22 #include <tizen.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * @file mdg.h
  30  */
  31
  32 /**
  33  * @addtogroup CAPI_NETWORK_MDG_MODULE
  34  * @{
  35  */
  36
  37 /**
  38  * @brief The mdg-manager handle.
  39  * @since_tizen 5.0
  40  */
  41 typedef void *mdg_h;
  42
  43 /**
  44  * @brief Base error codes for mdg-manager.
  45  *
  46  * @since_tizen 5.0
  47  */
  48 #ifndef TIZEN_ERROR_MDG
  49 #define TIZEN_ERROR_MDG -0x02F50000 /**< Base error code */
  50 #endif
  51
  52 /**
  53  * @brief Error codes for mdg-manager.
  54  *
  55  * @since_tizen 5.0
  56  */
  57 typedef enum {
  58         MDG_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  59         MDG_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */
  60         MDG_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  61         MDG_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  62         MDG_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
  63         MDG_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
  64         MDG_ERROR_OPERATION_FAILED = TIZEN_ERROR_MDG | 0x01, /**< operation failed */
  65         MDG_ERROR_NO_DATA = TIZEN_ERROR_MDG | 0x02, /**< Data not exists */
  66         MDG_ERROR_ALREADY_REGISTERED = TIZEN_ERROR_MDG | 0x03, /**< Request already registered */
  67         MDG_ERROR_IN_PROGRESS = TIZEN_ERROR_MDG | 0x04,/**< operation is in progress */
  68         MDG_ERROR_COMM_ERROR = TIZEN_ERROR_MDG | 0x05, /**< communication error in lower layer */
  69         MDG_ERROR_NOT_STARTED = TIZEN_ERROR_MDG | 0x06, /**< Service Not Started */
  70         MDG_ERROR_DB = TIZEN_ERROR_MDG | 0x07, /**< Internal DB error */
  71         MDG_ERROR_NOT_PROPER_GROUP = TIZEN_ERROR_MDG | 0x08, /**< Not proper group */
  72         MDG_ERROR_NOT_PROPER_DEVICE = TIZEN_ERROR_MDG | 0x09, /**< Not proper device */
  73 } mdg_error_e;
  74
  75 /**
  76  * @addtogroup CAPI_NETWORK_MDG_DEVICE_MODULE
  77  * @{
  78  */
  79
  80 /**
  81  * @brief Device handle.
  82  *
  83  * @since_tizen 5.0
  84  */
  85 typedef void *mdg_device_h; /**< Device handle */
  86
  87 /**
  88  * @}
  89  */
  90
  91 /**
  92  * @addtogroup CAPI_NETWORK_MDG_GROUP_MODULE
  93  * @{
  94  */
  95
  96 /**
  97  * @brief Group handle.
  98  *
  99  * @since_tizen 5.0
 100  */
 101 typedef void *mdg_group_h; /**< Group handle */
 102
 103 /**
 104  * @}
 105  */
 106
 107 /**
 108  * @brief Initializes mdg-manager.
 109  * @since_tizen 5.0
 110  * @privlevel public
 111  * @privilege %http://tizen.org/privilege/internet
 112  *
 113  * @remarks You must release @a handle using mdg_deinitialize().
 114  *
 115  * @param[out] handle The multi device group manager handle
 116  *
 117  * @return @c 0 on success, otherwise negative error value
 118  * @retval #MDG_ERROR_NONE Successful
 119  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 120  * @retval #MDG_ERROR_OPERATION_FAILED Operation failed
 121  * @retval #MDG_ERROR_OUT_OF_MEMORY Out of memory
 122  */
 123 int mdg_initialize(mdg_h *handle);
 124
 125 /**
 126  * @brief Deinitializes the mdg-manager.
 127  * @since_tizen 5.0
 128  * @privlevel public
 129  * @privilege %http://tizen.org/privilege/internet
 130  *
 131  * @param[in] handle The multi device group manager handle
 132  *
 133  * @return 0 on success, otherwise negative error value
 134  * @retval #MDG_ERROR_NONE Successful
 135  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 136  * @retval #MDG_ERROR_OPERATION_FAILED Operation failed
 137  */
 138 int mdg_deinitialize(mdg_h handle);
 139
 140 /**
 141  * @}
 142  */
 143
 144
 145 /**
 146  * @addtogroup CAPI_NETWORK_MDG_GROUP_MODULE
 147  * @{
 148  */
 149
 150 /**
 151  * @brief Group type.
 152  *
 153  * @since_tizen 5.0
 154  */
 155 typedef enum {
 156         MDG_GROUP_TYPE_LOCAL = 1, /**< Local group */
 157         MDG_GROUP_TYPE_REMOTE = 2, /**< Remote grojp */
 158 } mdg_group_type_e;
 159
 160 /**
 161  * @brief Called after mdg_group_find().
 162  * @details This function can receive a group resource found.
 163  *
 164  * @since_tizen 5.0
 165  * @privlevel public
 166  * @privilege %http://tizen.org/privilege/internet
 167  *
 168  * @remarks The @a group should not be released.
 169  * @remarks The @a group can be used only in the callback. To use outside, make a copy.
 170  *
 171  * @param[out] type Companion group type
 172  * @param[out] group Group resource found
 173  * @param[out] user_data User data pointer
 174  *
 175  * @pre The callback must be registered with mdg_group_find()
 176  *
 177  * @see mdg_group_find()
 178  */
 179 typedef bool (*mdg_group_found_cb)(mdg_group_type_e type,
 180                 mdg_group_h group, void *user_data);
 181
 182 /**
 183  * @brief Called after mdg_group_find() finished.
 184  * @details Called when the maximum wait time elapsed after the mdg_group_find() done.
 185  *
 186  * @since_tizen 5.0
 187  * @privlevel public
 188  * @privilege %http://tizen.org/privilege/internet
 189  *
 190  * @param[out] result Result of operation
 191  * @param[out] user_data User data pointer
 192  *
 193  * @pre The callback must be registered with mdg_group_find()
 194  *
 195  * @see mdg_group_find()
 196  */
 197 typedef void (*mdg_group_find_finish_cb)(int result, void *user_data);
 198
 199 /**
 200  * @brief Finds group resources in the network.
 201  * @details This function is find group resources in the network plus my local network.
 202  *
 203  * @since_tizen 5.0
 204  * @privlevel public
 205  * @privilege %http://tizen.org/privilege/internet
 206  *
 207  * @param[in] handle The multi device group manager handle
 208  * @param[in] timeout Time to find
 209  * @param[in] found_cb Callback handler to retrieve the found group resource
 210  * @param[in] finish_cb Callback handler to know finding process finished
 211  * @param[in] user_data User data poiter
 212  *
 213  * @return 0 on success, otherwise a negative error value.
 214  * @retval #MDG_ERROR_NONE Successful
 215  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 216  *
 217  * @see mdg_group_create()
 218  *
 219  */
 220 int mdg_group_find(mdg_h handle, int timeout,
 221                 mdg_group_found_cb found_cb, mdg_group_find_finish_cb finish_cb,
 222                 void *user_data);
 223
 224 /**
 225  * @}
 226  */
 227
 228 /**
 229  * @addtogroup CAPI_NETWORK_MDG_LOCAL_GROUP_MODULE
 230  * @{
 231  */
 232
 233 /**
 234  * @brief Creates a group.
 235  * @details This function is to allocate new group in local mdg-manager.
 236  *
 237  * @since_tizen 5.0
 238  * @privlevel public
 239  * @privilege %http://tizen.org/privilege/internet
 240  *
 241  * @param[in] handle The multi device group manager handle
 242  * @param[in] group_name Group name
 243  *
 244  * @return 0 on success, otherwise a negative error value.
 245  * @retval #MDG_ERROR_NONE Successful
 246  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 247  *
 248  * @see mdg_group_find()
 249  *
 250  */
 251 int mdg_group_create(mdg_h handle, char *group_name);
 252
 253 /**
 254  * @brief Deletes the group.
 255  * @details This function deletes a specific group and expels all devices in that group.
 256  *
 257  * @since_tizen 5.0
 258  * @privlevel public
 259  * @privilege %http://tizen.org/privilege/internet
 260  *
 261  * @param[in] handle The multi device group manager handle
 262  * @param[in] group Group handle
 263  *
 264  *
 265  * @return 0 on success, otherwise a negative error value.
 266  * @retval #MDG_ERROR_NONE Successful
 267  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 268  *
 269  * @see mdg_group_create()
 270  * @see mdg_request_join_group()
 271  * @see mdg_request_leave_group ()
 272  * @see mdg_group_merge()
 273  * @see mdg_group_get_member_devices()
 274  *
 275  */
 276 int mdg_group_delete(mdg_h handle, mdg_group_h group);
 277
 278 /**
 279  * @brief Called after mdg_group_invite_device().
 280  * @details Called when the maximum wait time elapsed or after the mdg_group_invite_device()
 281  * finished successfully.
 282  *
 283  * @since_tizen 5.0
 284  * @privlevel public
 285  * @privilege %http://tizen.org/privilege/internet
 286  *
 287  * @param[out] result Result of operation
 288  * @param[out] user_data User data pointer
 289  *
 290  * @pre The callback must be registered with mdg_group_invite_device()
 291  *
 292  * @see mdg_group_invite_device()
 293  */
 294 typedef bool (*mdg_group_foreach_cb)(mdg_device_h device, void *user_data);
 295
 296 /**
 297  * @brief Gets devices list in a group resource.
 298  * @details This function retrieves a devices list of group resources.
 299  *
 300  * @since_tizen 5.0
 301  * @privlevel public
 302  * @privilege %http://tizen.org/privilege/internet
 303  *
 304  * @remarks The @a devices should be released using mdg_device_info_destroy().
 305  *
 306  * @param[in] handle The multi device group manager handle
 307  * @param[in] group Group resource list
 308  * @param[out] devices Device list
 309  * @param[out] count Number of devices in a group
 310  *
 311  *
 312  * @return 0 on success, otherwise a negative error value.
 313  * @retval #MDG_ERROR_NONE Successful
 314  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 315  *
 316  * @see mdg_group_create()
 317  * @see mdg_request_join_group()
 318  * @see mdg_request_leave_group ()
 319  * @see mdg_group_delete()
 320  * @see mdg_group_merge()
 321  *
 322  */
 323 int mdg_group_foreach_device(mdg_h handle, mdg_group_h group,
 324         mdg_group_foreach_cb foreach_cb, void *user_data);
 325
 326 /**
 327  * @brief Called after mdg_group_invite_device().
 328  * @details Called when the maximum wait time elapsed or after the mdg_group_invite_device()
 329  * finished successfully.
 330  *
 331  * @since_tizen 5.0
 332  * @privlevel public
 333  * @privilege %http://tizen.org/privilege/internet
 334  *
 335  * @param[out] result Result of operation
 336  * @param[out] user_data User data pointer
 337  *
 338  * @pre The callback must be registered with mdg_group_invite_device()
 339  *
 340  * @see mdg_group_invite_device()
 341  */
 342 typedef void (*mdg_group_invite_device_finish_cb)(int result,
 343         mdg_device_h invited_device, void *user_data);
 344
 345 /**
 346  * @brief Called after mdg_group_eject_device().
 347  * @details Called when the maximum wait time elapsed or after the mdg_device_eject()
 348  * finished successfully.
 349  *
 350  * @since_tizen 5.0
 351  * @privlevel public
 352  * @privilege %http://tizen.org/privilege/internet
 353  *
 354  * @param[out] result Result of operation
 355  * @param[out] user_data User data pointer
 356  *
 357  * @pre The callback must be registered with mdg_device_eject()
 358  *
 359  * @see mdg_group_ejecct_device()
 360  */
 361 typedef void (*mdg_group_eject_device_finish_cb)(int result, void *user_data);
 362
 363 /**
 364  * @brief Requests to invite a device to the group which local device owns.
 365  * @details This function invites a remote device to a specific group. At the time of invitation,
 366  * user can enter the authentication information (i.e., PIN) or use the certificate.
 367  *
 368  * @since_tizen 5.0
 369  * @privlevel public
 370  * @privilege %http://tizen.org/privilege/internet
 371  *
 372  * @param[in] handle The multi device group manager handle
 373  * @param[in] group Group handle
 374  * @param[in] device Device handle
 375  * @param[in] PIN PIN number
 376  * @param[in] callback Callback handler to receive the result
 377  * @param[in] user_data User data poiter
 378  *
 379  *
 380  * @return 0 on success, otherwise a negative error value.
 381  * @retval #MDG_ERROR_NONE Successful
 382  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 383  *
 384  * @see mdg_request_create_group()
 385  * @see mdg_request_eject_device()
 386  * @see mdg_request_delete_group()
 387  * @see mdg_request_result_callback()
 388  * @see mdg_device_send_data()
 389  *
 390  */
 391 int mdg_group_invite_device(mdg_h handle, mdg_group_h group,
 392                 mdg_device_h device, char *PIN,
 393                 mdg_group_invite_device_finish_cb callback, void *user_data);
 394
 395 /**
 396  * @brief Requests to expel the device from the group which local device owns.
 397  * @details This function is used to kick away a remote devices in my local group.
 398  *
 399  * @since_tizen 5.0
 400  * @privlevel public
 401  * @privilege %http://tizen.org/privilege/internet
 402  *
 403  * @param[in] handle The multi device group manager handle
 404  * @param[in] group Group handle
 405  * @param[in] device Device handle
 406  * @param[in] callback Callback handler to receive the result
 407  * @param[in] user_data User data poiter
 408  *
 409  *
 410  * @return 0 on success, otherwise a negative error value.
 411  * @retval #MDG_ERROR_NONE Successful
 412  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 413  *
 414  * @see mdg_request_create_group()
 415  * @see mdg_request_eject_device()
 416  * @see mdg_request_delete_group()
 417  * @see mdg_request_result_callback()
 418  * @see mdg_device_send_data()
 419  *
 420  */
 421 int mdg_group_eject_device(mdg_h handle, mdg_group_h group,
 422                 mdg_device_h device, mdg_group_eject_device_finish_cb callback,
 423                 void *user_data);
 424
 425
 426 /**
 427  * @}
 428  */
 429
 430 /**
 431  * @addtogroup CAPI_NETWORK_MDG_REMOTE_GROUP_MODULE
 432  * @{
 433  */
 434
 435 /**
 436  * @brief Callback function potiner to be regsitered after sending requests.
 437  *
 438  * @since_tizen 5.0
 439  * @privlevel public
 440  * @privilege %http://tizen.org/privilege/internet
 441  *
 442  * @remarks The @a cmd, @arg should not be released.
 443  * @remarks The @a cmd, @arg can be used only in the callback. To use outside, make a copy.
 444  *
 445  * @param[out] cmd Command
 446  * @param[out] device_id Device id of requester
 447  * @param[out] arg Argument
 448  * @param[out] ret Return code
 449  * @param[out] user_data User data pointer
 450  *
 451  * @pre The callback must be registered with mdg_request_result_callback()
 452  *
 453  * @see mdg_request_result_callback()
 454  */
 455 typedef void (*mdg_request_result_cb)(char *cmd, char *device_id,
 456                                         unsigned char *arg, int len, int ret, void *user_data);
 457
 458 typedef void (*mdg_request_channel_list_finish_cb)(char *device_id, char *channel_id, void *user_data);
 459
 460 /**
 461  * @brief Requests to create a group.
 462  * @details We can create a group. This generated group can include device, and remote
 463  * devices can inquire remotely group information and device information included in group.
 464  *
 465  * @since_tizen 5.0
 466  * @privlevel public
 467  * @privilege %http://tizen.org/privilege/internet
 468  *
 469  * @param[in] handle The multi device group manager handle
 470  * @param[in] device Device handle
 471  * @param[in] group_name Group name
 472  * @param[in] cb Callback handler to receive the result
 473  * @param[in] user_data User data pointer
 474  *
 475  *
 476  * @return 0 on success, otherwise a negative error value.
 477  * @retval #MDG_ERROR_NONE Successful
 478  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 479  *
 480  * @see mdg_request_invite_device()
 481  * @see mdg_request_eject_device()
 482  * @see mdg_request_delete_group()
 483  * @see mdg_request_result_callback()
 484  * @see mdg_device_send_data()
 485  *
 486  */
 487 int mdg_request_create_group(mdg_h handle,
 488         mdg_device_h device, char *group_name, mdg_request_result_cb cb,
 489         void *user_data);
 490
 491 /**
 492  * @brief Requests to invite a device to the group.
 493  * @details This function invites a remote device to a specific group. At the time of
 494  * invitation, user can enter the authentication information (i.e., PIN) or use the
 495  * certificate.
 496  *
 497  * @since_tizen 5.0
 498  * @privlevel public
 499  * @privilege %http://tizen.org/privilege/internet
 500  *
 501  * @param[in] handle The multi device group manager handle
 502  * @param[in] group Group handle
 503  * @param[in] device Device handle
 504  * @param[in] PIN PIN number
 505  * @param[in] cb Callback handler to receive the result
 506  * @param[in] user_data User data pointer
 507  *
 508  *
 509  * @return 0 on success, otherwise a negative error value.
 510  * @retval #MDG_ERROR_NONE Successful
 511  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 512  *
 513  * @see mdg_request_create_group()
 514  * @see mdg_request_eject_device()
 515  * @see mdg_request_delete_group()
 516  * @see mdg_request_result_callback()
 517  * @see mdg_device_send_data()
 518  *
 519  */
 520 int mdg_request_invite_device(mdg_h handle, mdg_group_h group,
 521                 mdg_device_h device, char *PIN, mdg_request_result_cb cb,
 522                 void *user_data);
 523
 524 /**
 525  * @brief Requests to eject a device.
 526  * @details This function is used to kick away a remote devices in a specific group.
 527  *
 528  * @since_tizen 5.0
 529  * @privlevel public
 530  * @privilege %http://tizen.org/privilege/internet
 531  *
 532  * @param[in] handle The multi device group manager handle
 533  * @param[in] group Group handle
 534  * @param[in] device Device handle
 535  * @param[in] cb Callback handler to receive the result
 536  * @param[in] user_data User data pointer
 537  *
 538  *
 539  * @return 0 on success, otherwise a negative error value.
 540  * @retval #MDG_ERROR_NONE Successful
 541  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 542  *
 543  * @see mdg_request_create_group()
 544  * @see mdg_request_eject_device()
 545  * @see mdg_request_delete_group()
 546  * @see mdg_request_result_callback()
 547  * @see mdg_device_send_data()
 548  *
 549  */
 550 int mdg_request_eject_device(mdg_h handle, mdg_group_h group,
 551         mdg_device_h device, mdg_request_result_cb cb, void *user_data);
 552
 553 int mdg_request_channel_list(mdg_h handle, mdg_device_h device,
 554         mdg_request_channel_list_finish_cb finish_cb, void *user_data);
 555
 556 /**
 557  * @}
 558  */
 559
 560 /**
 561  * @addtogroup CAPI_NETWORK_MDG_GROUP_INFORMATION_MODULE
 562  * @{
 563  */
 564
 565 /**
 566  * @brief Clones the group handle.
 567  *
 568  * @since_tizen 5.0
 569  * @privlevel public
 570  *
 571  * @remarks The @a dst should be released using mdg_group_info_destroy().
 572  *
 573  * @param[out] dst Destination group handle
 574  * @param[in] src Source group handle
 575  *
 576  * @return 0 on success, otherwise a negative error value.
 577  * @retval #MDG_ERROR_NONE Successful
 578  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 579  *
 580  * @see mdg_group_info_create()
 581  * @see mdg_group_info_destroy()
 582  * @see mdg_group_info_get_type()
 583  * @see mdg_group_info_get_resource_type()
 584  * @see mdg_group_info_get_uri_path()
 585  * @see mdg_group_info_get_name()
 586  *
 587  */
 588 int mdg_group_info_clone(mdg_group_h *dst,
 589                 mdg_group_h src);
 590
 591 /**
 592  * @brief Destroys the group handle.
 593  *
 594  * @since_tizen 5.0
 595  * @privlevel public
 596  *
 597  * @param[in] group Group handle
 598  *
 599  * @return 0 on success, otherwise a negative error value.
 600  * @retval #MDG_ERROR_NONE Successful
 601  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 602  *
 603  * @see mdg_group_info_create()
 604  * @see mdg_group_info_clone()
 605  * @see mdg_group_info_get_type()
 606  * @see mdg_group_info_get_resource_type()
 607  * @see mdg_group_info_get_uri_path()
 608  * @see mdg_group_info_get_name()
 609  *
 610  */
 611 int mdg_group_info_destroy(mdg_group_h group);
 612
 613 int mdg_group_info_get_device_id(mdg_group_h group, char **device_id);
 614
 615 /**
 616  * @brief Gets group type of the group handle.
 617  *
 618  * @since_tizen 5.0
 619  * @privlevel public
 620  *
 621  * @param[in] group Group handle
 622  * @param[out] type Group type
 623  *
 624  * @return 0 on success, otherwise a negative error value.
 625  * @retval #MDG_ERROR_NONE Successful
 626  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 627  *
 628  * @see mdg_group_info_create()
 629  * @see mdg_group_info_clone()
 630  * @see mdg_group_info_destroy()
 631  * @see mdg_group_info_get_resource_type()
 632  * @see mdg_group_info_get_uri_path()
 633  * @see mdg_group_info_get_name()
 634  *
 635  */
 636 int mdg_group_info_get_type(mdg_group_h group, mdg_group_type_e *type);
 637
 638 /**
 639  * @brief Gets name of the group handle.
 640  *
 641  * @since_tizen 5.0
 642  * @privlevel public
 643  *
 644  * @remarks The @a name should be released using free().
 645  *
 646  * @param[in] group Group handle
 647  * @param[out] name Name of the group
 648  *
 649  * @return 0 on success, otherwise a negative error value.
 650  * @retval #MDG_ERROR_NONE Successful
 651  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 652  *
 653  * @see mdg_group_info_create()
 654  * @see mdg_group_info_clone()
 655  * @see mdg_group_info_destroy()
 656  * @see mdg_group_info_get_type()
 657  * @see mdg_group_info_get_resource_type()
 658  * @see mdg_group_info_get_uri_path()
 659  *
 660  */
 661 int mdg_group_info_get_name(mdg_group_h group, char **name);
 662
 663 /**
 664  * @}
 665  */
 666
 667
 668 /**
 669  * @addtogroup CAPI_NETWORK_MDG_DEVICE_MODULE
 670  * @{
 671  */
 672
 673 /**
 674  * @brief Device type.
 675  *
 676  * @since_tizen 5.0
 677  */
 678 typedef enum {
 679         MDG_DEVICE_TYPE_LOCAL = 1, /**< Local device */
 680         MDG_DEVICE_TYPE_REMOTE = 2, /**< Remote device */
 681 } mdg_device_type_e;
 682
 683 /**
 684  * @brief Called after mdg_device_find().
 685  * @details This function can receive a device found.
 686  *
 687  * @since_tizen 5.0
 688  * @privlevel public
 689  * @privilege %http://tizen.org/privilege/internet
 690  *
 691  * @remarks The @a device should not be released.
 692  * @remarks The @a device can be used only in the callback. To use outside, make a copy.
 693  *
 694  * @param[out] device Device found
 695  * @param[out] user_data User data pointer
 696  *
 697  * @pre The callback must be registered with mdg_device_find()
 698  *
 699  * @see mdg_device_find()
 700  */
 701 typedef bool (*mdg_device_found_cb)(mdg_device_h device, void *user_data);
 702
 703 /**
 704  * @brief Called after mdg_device_find() finished.
 705  * @details Called when the maximum wait time elapsed after the mdg_device_find() done.
 706  *
 707  * @since_tizen 5.0
 708   * @privlevel public
 709  * @privilege %http://tizen.org/privilege/internet
 710  *
 711  * @param[out] result Result of operation
 712  * @param[out] user_data User data pointer
 713  *
 714  * @pre The callback must be registered with mdg_device_find()
 715  *
 716  * @see mdg_device_find()
 717  */
 718 typedef void (*mdg_device_find_finish_cb)(int result, void *user_data);
 719
 720
 721 /**
 722  * @brief Called after mdg_device_send_data().
 723  * @details Called when the maximum wait time elapsed or after the mdg_device_send_data()
 724  * finished successfully.
 725  *
 726  * @since_tizen 5.0
 727  * @privlevel public
 728  * @privilege %http://tizen.org/privilege/internet
 729  *
 730  * @remarks The @a resp_data should not be released.
 731  * @remarks The @a resp_data can be used only in the callback. To use outside, make a copy.
 732  *
 733  * @param[out] result Result of operation
 734  * @param[out] resp_data Retrieved data
 735  * @param[out] user_data User data pointer
 736  *
 737  * @pre The callback must be registered with mdg_device_send_data()
 738  *
 739  * @see mdg_device_send_data()
 740  */
 741 typedef void (*mdg_device_send_data_finish_cb)(int result, void *user_data);
 742
 743 /**
 744  * @brief Gets my local device handle.
 745  * @details This function returns the local device information handle.
 746  *
 747  * @since_tizen 5.0
 748  *
 749  * @remarks The @a target should be released using mdg_device_info_destroy().
 750  *
 751  * @param[in] handle The multi device group manager handle
 752  * @param[in] device Local device handle
 753  *
 754  * @return 0 on success, otherwise a negative error value.
 755  * @retval #MDG_ERROR_NONE Successful
 756  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 757  * @retval #MDG_ERROR_NO_DATA No data
 758  *
 759  * @see mdg_device_info_get_my_uuid()
 760  *
 761  */
 762 int mdg_device_get_local_device(mdg_h handle,
 763                 mdg_device_h *device);
 764
 765 /**
 766  * @brief Finds candidate devices to include my groups in the network.
 767  * @details This function will search for candidate devices that can be included in local group.
 768  *
 769  * @since_tizen 5.0
 770  * @privlevel public
 771  * @privilege %http://tizen.org/privilege/internet
 772  *
 773  * @param[in] handle The multi device group manager handle
 774  * @param[in] timeout Time to find
 775  * @param[in] found_cb Callback handler to retrieve the found device
 776  * @param[in] finish_cb Callback handler to know finding process finished
 777  * @param[in] user_data User data poiter
 778  *
 779  *
 780  * @return 0 on success, otherwise a negative error value.
 781  * @retval #MDG_ERROR_NONE Successful
 782  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 783  *
 784  */
 785 int mdg_device_find(mdg_h handle, int timeout, bool is_invited,
 786                 mdg_device_found_cb found_cb, mdg_device_find_finish_cb finish_cb,
 787                 void *user_data);
 788
 789 typedef void (*mdg_channel_cb)(int result, char *device_id, char *channel_id,
 790                                         unsigned char *data, int data_length, void *user_data);
 791
 792 /* Server Side */
 793 int mdg_device_regist_channel(mdg_h handle, char *channel_id,
 794         mdg_channel_cb channel_cb, void *user_data);
 795
 796 int mdg_device_unregist_channel(mdg_h handle, char *channel_id);
 797
 798 /* Client Side */
 799 /**
 800  * @brief Sends data to the remote device.
 801  * @details We can send data to devices included in group.
 802  *
 803  * @since_tizen 5.0
 804  * @privlevel public
 805  * @privilege %http://tizen.org/privilege/internet
 806  *
 807  * @param[in] handle The multi device group manager handle
 808  * @param[in] device Device handle
 809  * @param[in] data Data to send
 810  * @param[in] len What length to send
 811  * @param[in] finish_cb Callback to be called after mdg_device_send_data() complete
 812  * @param[in] user_data User data pointer
 813  *
 814  *
 815  * @return 0 on success, otherwise a negative error value.
 816  * @retval #MDG_ERROR_NONE Successful
 817  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 818  *
 819  * @see mdg_request_create_group()
 820  * @see mdg_request_invite_device()
 821  * @see mdg_request_eject_device()
 822  * @see mdg_request_delete_group()
 823  * @see mdg_request_result_callback()
 824  *
 825  */
 826 int mdg_device_send_data(mdg_h handle, mdg_device_h device, char *channel_id,
 827                            unsigned char *data, int len,
 828                            mdg_device_send_data_finish_cb finish_cb, void *user_data);
 829
 830 /**
 831  * @}
 832  */
 833
 834 /**
 835  * @addtogroup CAPI_NETWORK_MDG_DEVICE_INFORMATION_MODULE
 836  * @{
 837  */
 838
 839 /**
 840  * @brief Clones the device handle.
 841  *
 842  * @since_tizen 5.0
 843  * @privlevel public
 844  *
 845  * @remarks The @a target should be released using mdg_device_info_destroy().
 846  *
 847  * @param[in] target Target device handle
 848  * @param[in] source Source device handle
 849  *
 850  * @return 0 on success, otherwise a negative error value.
 851  * @retval #MDG_ERROR_NONE Successful
 852  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 853  *
 854  * @see mdg_device_info_create()
 855  * @see mdg_device_info_destroy()
 856  * @see mdg_device_info_get_device_id()
 857  * @see mdg_device_info_get_ip()
 858  * @see mdg_device_info_get_device_type()
 859  * @see mdg_device_info_get_model_name()
 860  *
 861  */
 862 int mdg_device_info_clone(mdg_device_h *target,
 863                 mdg_device_h source);
 864
 865 /**
 866  * @brief Destroys the device handle.
 867  *
 868  * @since_tizen 5.0
 869  * @privlevel public
 870  *
 871  * @param[in] device Device handle
 872  *
 873  * @return 0 on success, otherwise a negative error value.
 874  * @retval #MDG_ERROR_NONE Successful
 875  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 876  *
 877  * @see mdg_device_info_create()
 878  * @see mdg_device_info_clone()
 879  * @see mdg_device_info_get_device_id()
 880  * @see mdg_device_info_get_ip()
 881  * @see mdg_device_info_get_device_type()
 882  * @see mdg_device_info_get_model_name()
 883  *
 884  */
 885 int mdg_device_info_destroy(mdg_device_h device);
 886
 887 /**
 888  * @brief Gets device ID of the device handle.
 889  *
 890  * @since_tizen 5.0
 891  * @privlevel public
 892  *
 893  * @remarks The @a device_id should be released using free().
 894  *
 895  * @param[in] device Device handle
 896  * @param[out] device_id Device ID
 897  *
 898  * @return 0 on success, otherwise a negative error value.
 899  * @retval #MDG_ERROR_NONE Successful
 900  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 901  *
 902  * @see mdg_device_info_create()
 903  * @see mdg_device_info_clone()
 904  * @see mdg_device_info_destroy()
 905  * @see mdg_device_info_get_ip()
 906  * @see mdg_device_info_get_device_type()
 907  * @see mdg_device_info_get_model_name()
 908  *
 909  */
 910 int mdg_device_info_get_device_id(mdg_device_h device,
 911                 char **device_id);
 912
 913 /**
 914  * @brief Gets IP of the device handle.
 915  *
 916  * @since_tizen 5.0
 917  * @privlevel public
 918  *
 919  * @remarks The @a ip should be released using free().
 920  *
 921  * @param[in] device Device handle
 922  * @param[out] ip IP address
 923  *
 924  * @return 0 on success, otherwise a negative error value.
 925  * @retval #MDG_ERROR_NONE Successful
 926  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 927  *
 928  * @see mdg_device_info_create()
 929  * @see mdg_device_info_clone()
 930  * @see mdg_device_info_destroy()
 931  * @see mdg_device_info_get_device_id()
 932  * @see mdg_device_info_get_device_type()
 933  * @see mdg_device_info_get_model_name()
 934  *
 935  */
 936 int mdg_device_info_get_addr(mdg_device_h device, char **addr);
 937 int mdg_device_info_get_port(mdg_device_h device, int *port);
 938 int mdg_device_info_get_secure_port(mdg_device_h device, int *secure_port);
 939
 940 /**
 941  * @brief Gets model name of the device handle.
 942  *
 943  * @since_tizen 5.0
 944  * @privlevel public
 945  *
 946  * @remarks The @a model_name should be released using free().
 947  *
 948  * @param[in] device Device handle
 949  * @param[out] model_name Model name
 950  *
 951  * @return 0 on success, otherwise a negative error value.
 952  * @retval #MDG_ERROR_NONE Successful
 953  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 954  *
 955  * @see mdg_device_info_create()
 956  * @see mdg_device_info_clone()
 957  * @see mdg_device_info_destroy()
 958  * @see mdg_device_info_get_device_id()
 959  * @see mdg_device_info_get_ip()
 960  * @see mdg_device_info_get_device_type()
 961  *
 962  */
 963 int mdg_device_info_get_model_name(mdg_device_h device, char **model_name);
 964 int mdg_device_info_get_device_name(mdg_device_h device, char **device_name);
 965 int mdg_device_info_get_platform_ver(mdg_device_h device, char **platform_ver);
 966 int mdg_device_info_get_vendor_id(mdg_device_h device, char **vendor_id);
 967 int mdg_device_info_get_profile(mdg_device_h device, char **profile);
 968 int mdg_device_info_is_invited(mdg_device_h device, bool *is_invited);
 969
 970 /**
 971  * @brief Gets device type of the device handle.
 972  *
 973  * @since_tizen 5.0
 974  * @privlevel public
 975  *
 976  * @remarks The @a device_type should be released using free().
 977  *
 978  * @param[in] device Device handle
 979  * @param[out] device_type Device type
 980  *
 981  * @return 0 on success, otherwise a negative error value.
 982  * @retval #MDG_ERROR_NONE Successful
 983  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 984  *
 985  * @see mdg_device_info_create()
 986  * @see mdg_device_info_clone()
 987  * @see mdg_device_info_destroy()
 988  * @see mdg_device_info_get_device_id()
 989  * @see mdg_device_info_get_ip()
 990  * @see mdg_device_info_get_model_name()
 991  *
 992  */
 993 int mdg_device_info_get_type(mdg_device_h device,
 994                 mdg_device_type_e *device_type);
 995
 996 /**
 997  * @}
 998  */
 999
1000
1001 #ifdef __cplusplus
1002 }
1003 #endif
1004
1005 #endif /* __TIZEN_NETWORK_MULTI_DEVICE_GROUP_MDG_H__ */