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  * @see mdg_group_info_get_host_addr()
 587  *
 588  */
 589 int mdg_group_info_clone(mdg_group_h *dst,
 590                 mdg_group_h src);
 591
 592 /**
 593  * @brief Destroys the group handle.
 594  *
 595  * @since_tizen 5.0
 596  * @privlevel public
 597  *
 598  * @param[in] group Group handle
 599  *
 600  * @return 0 on success, otherwise a negative error value.
 601  * @retval #MDG_ERROR_NONE Successful
 602  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 603  *
 604  * @see mdg_group_info_create()
 605  * @see mdg_group_info_clone()
 606  * @see mdg_group_info_get_type()
 607  * @see mdg_group_info_get_resource_type()
 608  * @see mdg_group_info_get_uri_path()
 609  * @see mdg_group_info_get_name()
 610  * @see mdg_group_info_get_host_addr()
 611  *
 612  */
 613 int mdg_group_info_destroy(mdg_group_h group);
 614
 615 int mdg_group_info_get_device_id(mdg_group_h group, char **device_id);
 616 int mdg_group_info_get_host_addr(mdg_group_h group, char **host_addr);
 617
 618 /**
 619  * @brief Gets group type of the group handle.
 620  *
 621  * @since_tizen 5.0
 622  * @privlevel public
 623  *
 624  * @param[in] group Group handle
 625  * @param[out] type Group type
 626  *
 627  * @return 0 on success, otherwise a negative error value.
 628  * @retval #MDG_ERROR_NONE Successful
 629  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 630  *
 631  * @see mdg_group_info_create()
 632  * @see mdg_group_info_clone()
 633  * @see mdg_group_info_destroy()
 634  * @see mdg_group_info_get_resource_type()
 635  * @see mdg_group_info_get_uri_path()
 636  * @see mdg_group_info_get_name()
 637  * @see mdg_group_info_get_host_addr()
 638  *
 639  */
 640 int mdg_group_info_get_type(mdg_group_h group, mdg_group_type_e *type);
 641
 642 /**
 643  * @brief Gets name of the group handle.
 644  *
 645  * @since_tizen 5.0
 646  * @privlevel public
 647  *
 648  * @remarks The @a name should be released using free().
 649  *
 650  * @param[in] group Group handle
 651  * @param[out] name Name of the group
 652  *
 653  * @return 0 on success, otherwise a negative error value.
 654  * @retval #MDG_ERROR_NONE Successful
 655  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 656  *
 657  * @see mdg_group_info_create()
 658  * @see mdg_group_info_clone()
 659  * @see mdg_group_info_destroy()
 660  * @see mdg_group_info_get_type()
 661  * @see mdg_group_info_get_resource_type()
 662  * @see mdg_group_info_get_uri_path()
 663  * @see mdg_group_info_get_host_addr()
 664  *
 665  */
 666 int mdg_group_info_get_name(mdg_group_h group, char **name);
 667
 668 /**
 669  * @}
 670  */
 671
 672
 673 /**
 674  * @addtogroup CAPI_NETWORK_MDG_DEVICE_MODULE
 675  * @{
 676  */
 677
 678 /**
 679  * @brief Device type.
 680  *
 681  * @since_tizen 5.0
 682  */
 683 typedef enum {
 684         MDG_DEVICE_TYPE_LOCAL = 1, /**< Local device */
 685         MDG_DEVICE_TYPE_REMOTE = 2, /**< Remote device */
 686 } mdg_device_type_e;
 687
 688 /**
 689  * @brief Called after mdg_device_find().
 690  * @details This function can receive a device found.
 691  *
 692  * @since_tizen 5.0
 693  * @privlevel public
 694  * @privilege %http://tizen.org/privilege/internet
 695  *
 696  * @remarks The @a device should not be released.
 697  * @remarks The @a device can be used only in the callback. To use outside, make a copy.
 698  *
 699  * @param[out] device Device found
 700  * @param[out] user_data User data pointer
 701  *
 702  * @pre The callback must be registered with mdg_device_find()
 703  *
 704  * @see mdg_device_find()
 705  */
 706 typedef bool (*mdg_device_found_cb)(mdg_device_h device, void *user_data);
 707
 708 /**
 709  * @brief Called after mdg_device_find() finished.
 710  * @details Called when the maximum wait time elapsed after the mdg_device_find() done.
 711  *
 712  * @since_tizen 5.0
 713   * @privlevel public
 714  * @privilege %http://tizen.org/privilege/internet
 715  *
 716  * @param[out] result Result of operation
 717  * @param[out] user_data User data pointer
 718  *
 719  * @pre The callback must be registered with mdg_device_find()
 720  *
 721  * @see mdg_device_find()
 722  */
 723 typedef void (*mdg_device_find_finish_cb)(int result, void *user_data);
 724
 725
 726 /**
 727  * @brief Called after mdg_device_send_data().
 728  * @details Called when the maximum wait time elapsed or after the mdg_device_send_data()
 729  * finished successfully.
 730  *
 731  * @since_tizen 5.0
 732  * @privlevel public
 733  * @privilege %http://tizen.org/privilege/internet
 734  *
 735  * @remarks The @a resp_data should not be released.
 736  * @remarks The @a resp_data can be used only in the callback. To use outside, make a copy.
 737  *
 738  * @param[out] result Result of operation
 739  * @param[out] resp_data Retrieved data
 740  * @param[out] user_data User data pointer
 741  *
 742  * @pre The callback must be registered with mdg_device_send_data()
 743  *
 744  * @see mdg_device_send_data()
 745  */
 746 typedef void (*mdg_device_send_data_finish_cb)(int result, void *user_data);
 747
 748 /**
 749  * @brief Gets my local device handle.
 750  * @details This function returns the local device information handle.
 751  *
 752  * @since_tizen 5.0
 753  *
 754  * @remarks The @a target should be released using mdg_device_info_destroy().
 755  *
 756  * @param[in] handle The multi device group manager handle
 757  * @param[in] device Local device handle
 758  *
 759  * @return 0 on success, otherwise a negative error value.
 760  * @retval #MDG_ERROR_NONE Successful
 761  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 762  * @retval #MDG_ERROR_NO_DATA No data
 763  *
 764  * @see mdg_device_info_get_my_uuid()
 765  *
 766  */
 767 int mdg_device_get_local_device(mdg_h handle,
 768                 mdg_device_h *device);
 769
 770 /**
 771  * @brief Finds candidate devices to include my groups in the network.
 772  * @details This function will search for candidate devices that can be included in local group.
 773  *
 774  * @since_tizen 5.0
 775  * @privlevel public
 776  * @privilege %http://tizen.org/privilege/internet
 777  *
 778  * @param[in] handle The multi device group manager handle
 779  * @param[in] timeout Time to find
 780  * @param[in] found_cb Callback handler to retrieve the found device
 781  * @param[in] finish_cb Callback handler to know finding process finished
 782  * @param[in] user_data User data poiter
 783  *
 784  *
 785  * @return 0 on success, otherwise a negative error value.
 786  * @retval #MDG_ERROR_NONE Successful
 787  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 788  *
 789  */
 790 int mdg_device_find(mdg_h handle, int timeout, bool is_invited,
 791                 mdg_device_found_cb found_cb, mdg_device_find_finish_cb finish_cb,
 792                 void *user_data);
 793
 794 typedef void (*mdg_channel_cb)(int result, char *device_id, char *channel_id,
 795                                         unsigned char *data, int data_length, void *user_data);
 796
 797 /* Server Side */
 798 int mdg_device_regist_channel(mdg_h handle, char *channel_id,
 799         mdg_channel_cb channel_cb, void *user_data);
 800
 801 int mdg_device_unregist_channel(mdg_h handle, char *channel_id);
 802
 803 /* Client Side */
 804 /**
 805  * @brief Sends data to the remote device.
 806  * @details We can send data to devices included in group.
 807  *
 808  * @since_tizen 5.0
 809  * @privlevel public
 810  * @privilege %http://tizen.org/privilege/internet
 811  *
 812  * @param[in] handle The multi device group manager handle
 813  * @param[in] device Device handle
 814  * @param[in] data Data to send
 815  * @param[in] len What length to send
 816  * @param[in] finish_cb Callback to be called after mdg_device_send_data() complete
 817  * @param[in] user_data User data pointer
 818  *
 819  *
 820  * @return 0 on success, otherwise a negative error value.
 821  * @retval #MDG_ERROR_NONE Successful
 822  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 823  *
 824  * @see mdg_request_create_group()
 825  * @see mdg_request_invite_device()
 826  * @see mdg_request_eject_device()
 827  * @see mdg_request_delete_group()
 828  * @see mdg_request_result_callback()
 829  *
 830  */
 831 int mdg_device_send_data(mdg_h handle, mdg_device_h device, char *channel_id,
 832                            unsigned char *data, int len,
 833                            mdg_device_send_data_finish_cb finish_cb, void *user_data);
 834
 835 typedef void (*mdg_send_file_progress_cb)(const char *file_path, long send_size,
 836                 long total_size, int percent, void *user_data);
 837 typedef void (*mdg_send_file_finish_cb)(int result, mdg_device_h device, void *user_data);
 838
 839 int mdg_device_send_file(mdg_h handle, mdg_device_h device, char *file_path,
 840                            mdg_send_file_progress_cb progress_cb, mdg_send_file_finish_cb finish_cb, void *user_data);
 841
 842 /**
 843  * @}
 844  */
 845
 846 /**
 847  * @addtogroup CAPI_NETWORK_MDG_DEVICE_INFORMATION_MODULE
 848  * @{
 849  */
 850
 851 /**
 852  * @brief Clones the device handle.
 853  *
 854  * @since_tizen 5.0
 855  * @privlevel public
 856  *
 857  * @remarks The @a target should be released using mdg_device_info_destroy().
 858  *
 859  * @param[in] target Target device handle
 860  * @param[in] source Source device handle
 861  *
 862  * @return 0 on success, otherwise a negative error value.
 863  * @retval #MDG_ERROR_NONE Successful
 864  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 865  *
 866  * @see mdg_device_info_create()
 867  * @see mdg_device_info_destroy()
 868  * @see mdg_device_info_get_device_id()
 869  * @see mdg_device_info_get_ip()
 870  * @see mdg_device_info_get_device_type()
 871  * @see mdg_device_info_get_model_name()
 872  *
 873  */
 874 int mdg_device_info_clone(mdg_device_h *target,
 875                 mdg_device_h source);
 876
 877 /**
 878  * @brief Destroys the device handle.
 879  *
 880  * @since_tizen 5.0
 881  * @privlevel public
 882  *
 883  * @param[in] device Device handle
 884  *
 885  * @return 0 on success, otherwise a negative error value.
 886  * @retval #MDG_ERROR_NONE Successful
 887  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 888  *
 889  * @see mdg_device_info_create()
 890  * @see mdg_device_info_clone()
 891  * @see mdg_device_info_get_device_id()
 892  * @see mdg_device_info_get_ip()
 893  * @see mdg_device_info_get_device_type()
 894  * @see mdg_device_info_get_model_name()
 895  *
 896  */
 897 int mdg_device_info_destroy(mdg_device_h device);
 898
 899 /**
 900  * @brief Gets device ID of the device handle.
 901  *
 902  * @since_tizen 5.0
 903  * @privlevel public
 904  *
 905  * @remarks The @a device_id should be released using free().
 906  *
 907  * @param[in] device Device handle
 908  * @param[out] device_id Device ID
 909  *
 910  * @return 0 on success, otherwise a negative error value.
 911  * @retval #MDG_ERROR_NONE Successful
 912  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 913  *
 914  * @see mdg_device_info_create()
 915  * @see mdg_device_info_clone()
 916  * @see mdg_device_info_destroy()
 917  * @see mdg_device_info_get_ip()
 918  * @see mdg_device_info_get_device_type()
 919  * @see mdg_device_info_get_model_name()
 920  *
 921  */
 922 int mdg_device_info_get_device_id(mdg_device_h device,
 923                 char **device_id);
 924
 925 /**
 926  * @brief Gets IP of the device handle.
 927  *
 928  * @since_tizen 5.0
 929  * @privlevel public
 930  *
 931  * @remarks The @a ip should be released using free().
 932  *
 933  * @param[in] device Device handle
 934  * @param[out] ip IP address
 935  *
 936  * @return 0 on success, otherwise a negative error value.
 937  * @retval #MDG_ERROR_NONE Successful
 938  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 939  *
 940  * @see mdg_device_info_create()
 941  * @see mdg_device_info_clone()
 942  * @see mdg_device_info_destroy()
 943  * @see mdg_device_info_get_device_id()
 944  * @see mdg_device_info_get_device_type()
 945  * @see mdg_device_info_get_model_name()
 946  *
 947  */
 948 int mdg_device_info_get_addr(mdg_device_h device, char **addr);
 949 int mdg_device_info_get_port(mdg_device_h device, int *port);
 950 int mdg_device_info_get_secure_port(mdg_device_h device, int *secure_port);
 951
 952 /**
 953  * @brief Gets model name of the device handle.
 954  *
 955  * @since_tizen 5.0
 956  * @privlevel public
 957  *
 958  * @remarks The @a model_name should be released using free().
 959  *
 960  * @param[in] device Device handle
 961  * @param[out] model_name Model name
 962  *
 963  * @return 0 on success, otherwise a negative error value.
 964  * @retval #MDG_ERROR_NONE Successful
 965  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 966  *
 967  * @see mdg_device_info_create()
 968  * @see mdg_device_info_clone()
 969  * @see mdg_device_info_destroy()
 970  * @see mdg_device_info_get_device_id()
 971  * @see mdg_device_info_get_ip()
 972  * @see mdg_device_info_get_device_type()
 973  *
 974  */
 975 int mdg_device_info_get_model_name(mdg_device_h device, char **model_name);
 976 int mdg_device_info_get_device_name(mdg_device_h device, char **device_name);
 977 int mdg_device_info_get_platform_ver(mdg_device_h device, char **platform_ver);
 978 int mdg_device_info_get_vendor_id(mdg_device_h device, char **vendor_id);
 979 int mdg_device_info_get_profile(mdg_device_h device, char **profile);
 980 int mdg_device_info_is_invited(mdg_device_h device, bool *is_invited);
 981
 982 /**
 983  * @brief Gets device type of the device handle.
 984  *
 985  * @since_tizen 5.0
 986  * @privlevel public
 987  *
 988  * @remarks The @a device_type should be released using free().
 989  *
 990  * @param[in] device Device handle
 991  * @param[out] device_type Device type
 992  *
 993  * @return 0 on success, otherwise a negative error value.
 994  * @retval #MDG_ERROR_NONE Successful
 995  * @retval #MDG_ERROR_INVALID_PARAMETER Invalid parameter
 996  *
 997  * @see mdg_device_info_create()
 998  * @see mdg_device_info_clone()
 999  * @see mdg_device_info_destroy()
1000  * @see mdg_device_info_get_device_id()
1001  * @see mdg_device_info_get_ip()
1002  * @see mdg_device_info_get_model_name()
1003  *
1004  */
1005 int mdg_device_info_get_type(mdg_device_h device,
1006                 mdg_device_type_e *device_type);
1007
1008 /**
1009  * @}
1010  */
1011
1012
1013 #ifdef __cplusplus
1014 }
1015 #endif
1016
1017 #endif /* __TIZEN_NETWORK_MULTI_DEVICE_GROUP_MDG_H__ */