include/vine.h

   1 /*
   2  * Copyright (c) 2021 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 __VINE_H__
  19 #define __VINE_H__
  20
  21 #include <errno.h>
  22 #include <stdio.h>
  23 #include <stdbool.h>
  24
  25 #ifdef TIZEN_OS
  26 #include <tizen.h>
  27 #endif
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /**
  34  * @file vine.h
  35  */
  36
  37 /**
  38  * @addtogroup VINE_MODULE
  39  * @{
  40  */
  41
  42 #ifndef VINE_ERROR
  43 #define VINE_ERROR -0x03050000
  44 #endif
  45
  46 /**
  47  * @brief Enumeration for Vine error code.
  48  * @since_tizen 6.5
  49  */
  50 typedef enum {
  51         /**
  52          * Successful
  53          */
  54         VINE_ERROR_NONE = 0,
  55         /**
  56          * Operation not permitted(1)
  57          */
  58         VINE_ERROR_NOT_PERMITTED = -EPERM,
  59         /**
  60          * Out of memory(12)
  61          */
  62         VINE_ERROR_OUT_OF_MEMORY = -ENOMEM,
  63         /**
  64          * Permission denied(13)
  65          */
  66         VINE_ERROR_PERMISSION_DENIED = -EACCES,
  67         /**
  68          * Invalid function parameter(22)
  69          */
  70         VINE_ERROR_INVALID_PARAMETER = -EINVAL,
  71         /**
  72          * Invalid operation(38)
  73          */
  74         VINE_ERROR_INVALID_OPERATION = -ENOSYS,
  75         /**
  76          * Connection timed out(110)
  77          */
  78         VINE_ERROR_CONNECTION_TIME_OUT = -ETIMEDOUT,
  79         /**
  80          * Now in progress(115)
  81          */
  82         VINE_ERROR_NOW_IN_PROGRESS = -EINPROGRESS,
  83         /**
  84          * Not supported
  85          */
  86         VINE_ERROR_NOT_SUPPORTED,
  87         /**
  88          * No initialized
  89          */
  90         VINE_ERROR_NOT_INITIALIZED = VINE_ERROR|0x01,
  91         /**
  92          * Already initialized
  93          */
  94         VINE_ERROR_ALREADY_INITIALIZED = VINE_ERROR|0x02,
  95         /**
  96          * Already enabled
  97          */
  98         VINE_ERROR_ALREADY_ENABLED = VINE_ERROR|0x03,
  99         /**
 100          * Operation failed
 101          */
 102         VINE_ERROR_OPERATION_FAILED = VINE_ERROR|0x04,
 103         /**
 104          * Service name conflicted
 105          */
 106         VINE_ERROR_NAME_CONFLICT = VINE_ERROR|0x05,
 107         /**
 108          * No read data
 109          */
 110         VINE_ERROR_NO_READ_DATA = VINE_ERROR|0x06,
 111         /**
 112          * Rejected by peer
 113          */
 114         //VINE_ERROR_REJECTED_BY_PEER = VINE_ERROR|0x05,
 115         /**
 116          * Wi-Fi Interface is down
 117          */
 118         //VINE_ERROR_INTERFACE_DOWN = -ENETDOWN,
 119 } vine_error_e;
 120
 121
 122 /**
 123  * @brief Enumeration for data path type
 124  * @since_tizen 6.5
 125  */
 126 typedef enum {
 127         /**
 128          * Server type
 129          */
 130         VINE_DP_TYPE_SERVER = 0,
 131         /**
 132          * Client type
 133          */
 134         VINE_DP_TYPE_CLIENT,
 135         /**
 136          * Publish-Subscirbe type
 137          */
 138         VINE_DP_TYPE_PUBSUB,
 139         /**
 140          * Unknown
 141          */
 142         VINE_DP_TYPE_UNKNOWN
 143 } vine_dp_type_e;
 144
 145 /**
 146  * @brief Enumeration for security configuration
 147  * @since_tizen 6.5
 148  */
 149 typedef enum {
 150         /**
 151          * No security type
 152          */
 153         VINE_SECURITY_TYPE_NONE = 0,
 154         /**
 155          * Uses TLS/SSL for encrypted communication
 156          */
 157         VINE_SECURITY_TYPE_TLS = 1,
 158         /**
 159          * Attempts PSK authentication over TLS connection
 160          */
 161         VINE_SECURITY_TYPE_PSK_OVER_TLS = 2,
 162 } vine_security_type_e;
 163
 164 /**
 165  * @brief Enumeration for TLS version
 166  * @since_tizen 6.5
 167  */
 168 typedef enum {
 169         /**
 170          * Default TLS version
 171          */
 172         VINE_SECURITY_TLS_VERSION_DEFAULT = 0,
 173         /**
 174          * TLS 1.0 or later
 175          */
 176         VINE_SECURITY_TLS_VERSION_1_0 = 100,
 177         /**
 178          * TLS 1.1 or later
 179          */
 180         VINE_SECURITY_TLS_VERSION_1_1 = 101,
 181         /**
 182          * TLS 1.2 or later
 183          */
 184         VINE_SECURITY_TLS_VERSION_1_2 = 102,
 185         /**
 186          * TLS 1.3 or later
 187          */
 188         VINE_SECURITY_TLS_VERSION_1_3 = 103,
 189 } vine_security_tls_version_e;
 190
 191 /**
 192  * @brief Enumeration for certificate verification flag
 193  * @since_tizen 6.5
 194  */
 195 typedef enum {
 196         /**
 197          * Default.
 198          */
 199         VINE_SECURITY_VERIFICATION_FLAG_DEFAULT = 0,
 200         /**
 201          * Allows self-signed ceritifcate
 202          */
 203         VINE_SECURITY_VERIFICATION_FLAG_ALLOW_SELF_SIGNED = (1 << 0),
 204         /**
 205          * Skips host name(CN) check
 206          */
 207         VINE_SECURITY_VERIFICATION_FLAG_SKIP_HOST_NAME_CHECK = (1 << 1),
 208 } vine_security_verification_flag_e;
 209
 210 typedef enum {
 211         /**
 212          * The discovered service is unavailable
 213          */
 214         VINE_SERVICE_UNAVAILABLE = 0,
 215         /**
 216          * The discovered service is available
 217          */
 218         VINE_SERVICE_AVAILABLE,
 219 } vine_service_state_e;
 220
 221 /**
 222  * @brief Enumeration for capability type.
 223  * @since_tizen 6.5
 224  */
 225 typedef enum {
 226         /**
 227          * The possible discovery methods.
 228          */
 229         VINE_CAPA_DISCOVERY_METHODS = 0,
 230         /**
 231          * The max number of connections.
 232          */
 233         VINE_CAPA_MAX_CONNECTIONS,
 234 } vine_capability_type_e;
 235
 236 /**
 237  * @brief Publish Session
 238  * @since_tizen 6.5
 239  */
 240 typedef void *vine_session_h;
 241
 242 /**
 243  * @brief Service
 244  * @since_tizen 6.5
 245  */
 246 typedef void *vine_service_h;
 247
 248 /**
 249  * @brief Data Path
 250  * @since_tizen 6.5
 251  */
 252 typedef void *vine_dp_h;
 253
 254 /**
 255  * @brief Security configuration
 256  * @since_tizen 6.5
 257  */
 258 typedef void *vine_security_h;
 259
 260 /**
 261  * @brief Enumeration for service discovery method
 262  * @since_tizen 6.5
 263  */
 264 typedef enum {
 265         VINE_DISCOVERY_METHOD_DNS_SD = 0,
 266 } vine_discovery_method_e;
 267
 268 /**
 269  * @brief Enumeration for address family
 270  * @since_tizen 6.5
 271  */
 272 typedef enum {
 273         /*
 274          * Default.
 275          * IPv6 has a higher priority than IPv4.
 276          * For example, IPv6 is used in the dual stack.
 277          */
 278         VINE_ADDRESS_FAMILY_DEFAULT = 0,
 279         /**
 280          * IPv4 only.
 281          */
 282         VINE_ADDRESS_FAMILY_IPV4,
 283         /**
 284          * IPv6 only.
 285          */
 286         VINE_ADDRESS_FAMILY_IPV6,
 287 } vine_address_family_e;
 288
 289 /**
 290  * @brief Initializes Vine.
 291  * @since_tizen 6.5
 292  * @return 0 on success, otherwise a negative error value
 293  * @retval #VINE_ERROR_NONE     Successful
 294  * @retval #VINE_ERROR_ALREADY_INITIALIZED      Already initialized
 295  * @retval #VINE_ERROR_OPERATION_FAILED Operation failed
 296  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 297  * @see vine_deinitialize()
 298  */
 299 int vine_initialize();
 300
 301 /**
 302  * @brief Deinitializes Vine.
 303  * @since_tizen 6.5
 304  * @return 0 on success, otherwise a negative error value
 305  * @retval #VINE_ERROR_NONE     Successful
 306  * @retval #VINE_ERROR_NOT_INITIALIZED  Not initialized
 307  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 308  * @see vine_initialize()
 309  */
 310 int vine_deinitialize();
 311
 312 /**
 313  * @brief Gets the capabilities corresponding to @a type.
 314  * @since_tizen 6.5
 315  * @param[in] type  The type of capability
 316  * @param[out] capabilities The capabilites
 317  * @return 0 on success, otherwise a negative error value
 318  * @retval #VINE_ERROR_NONE     Successful
 319  * @retval #VINE_ERROR_NOT_INITIALIZED  Not initialized
 320  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 321  * @see vine_initialize()
 322  */
 323 int vine_get_capabilities(vine_capability_type_e type, int *capabilities);
 324
 325 /**
 326  * @brief Gets event file discriptor for monitoring Vine events.
 327  * @since_tizen 6.5
 328  * @param[in] session The session handle
 329  * @param[out] fd The event fd
 330  * @return 0 on success, otherwise a negative error value
 331  * @retval #VINE_ERROR_NONE     Successful
 332  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 333  */
 334 int vine_session_get_event_fd(vine_session_h session, int *fd);
 335
 336 /**
 337  * @brief Process occurred event.
 338  * @remarks This function should be called in event thread or context.
 339  * @since_tizen 6.5
 340  * @param[in] session The session handle
 341  * @return 0 on success, otherwise a negative error value
 342  * @retval #VINE_ERROR_NONE     Successful
 343  * @retval #VINE_ERROR_NOT_INITIALIZED  Not initialized
 344  * @retval #VINE_ERROR_OPERATION_FAILED Operation failed
 345  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 346  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 347  */
 348 int vine_session_process_event(vine_session_h session);
 349
 350 /**
 351  * @brief Creates a session.
 352  * @since_tizen 6.5
 353  * @param[out] session The session handle
 354  * @return 0 on success, otherwise a negative error value
 355  * @retval #VINE_ERROR_NONE     Successful
 356  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 357  * @retval #VINE_ERROR_OUT_OF_MEMORY    Out of memory
 358  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 359  * @see vine_initialize()
 360  */
 361 int vine_session_create(vine_session_h *session);
 362
 363 /**
 364  * @brief Destroys a publish session.
 365  * @since_tizen 6.5
 366  * @param[in] session The session handle
 367  * @return 0 on success, otherwise a negative error value
 368  * @retval #VINE_ERROR_NONE     Successful
 369  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 370  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 371  * @see vine_initialize()
 372  */
 373 int vine_session_destroy(vine_session_h session);
 374
 375 /**
 376  * @brief Called when service is registered.
 377  * @since_tizen 6.5
 378  * @param[in] session The session handle
 379  * @param[in] service_name The registered service name
 380  * @param[in] error The result of registration
 381  * @param[in] user_data The user data passed from the callback registration function
 382  * @see vine_session_set_registered_cb()
 383  * @see vine_session_unset_registered_cb()
 384  */
 385 typedef void(*vine_session_registered_cb)(vine_session_h session,
 386                 const char *service_name, vine_error_e error, void *user_data);
 387
 388 /**
 389  * @brief Sets registered callback called when service is registered.
 390  * @since_tizen 6.5
 391  * @param[in] session The session handle
 392  * @param[in] callback The registered callback
 393  * @param[in] user_data The user data
 394  * @return 0 on success, otherwise a negative error value
 395  * @retval #VINE_ERROR_NONE     Successful
 396  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 397  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 398  * @see vine_session_unset_registered_cb()
 399  */
 400 int vine_session_set_registered_cb(vine_session_h session,
 401                 vine_session_registered_cb callback, void *user_data);
 402
 403 /**
 404  * @brief Unsets registered callback.
 405  * @since_tizen 6.5
 406  * @param[in] session The session handle
 407  * @return 0 on success, otherwise a negative error value
 408  * @retval #VINE_ERROR_NONE     Successful
 409  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 410  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 411  * @see vine_session_set_registered_cb()
 412  */
 413 int vine_session_unset_registered_cb(vine_session_h session);
 414
 415 /**
 416  * @brief Called when service is discovered.
 417  * @remarks @a service will be freed after this callback. Use @a vine_service_clone().
 418  * @since_tizen 6.5
 419  * @param[in] session The session handle
 420  * @param[in] discovered_service The discovered service
 421  * @param[in] state The availability of the discovered service
 422  * @param[in] user_data The user data passed from the callback registration function
 423  * @see vine_session_set_discovered_cb()
 424  * @see vine_session_unset_discovered_cb()
 425  */
 426 typedef void(*vine_session_discovered_cb)(vine_session_h session,
 427                 vine_service_h discovered_service, vine_service_state_e state, void *user_data);
 428
 429 /**
 430  * @brief Registers discovered callback called when service is discovered.
 431  * @since_tizen 6.5
 432  * @param[in] session The session handle
 433  * @param[in] callback The discovered callback
 434  * @param[in] user_data The user data
 435  * @return 0 on success, otherwise a negative error value
 436  * @retval #VINE_ERROR_NONE     Successful
 437  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 438  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 439  * @see vine_session_unset_discovered_cb()
 440  */
 441 int vine_session_set_discovered_cb(vine_session_h session,
 442                 vine_session_discovered_cb callback, void *user_data);
 443
 444 /**
 445  * @brief Unregisters discovered callback.
 446  * @since_tizen 6.5
 447  * @param[in] session The session handle
 448  * @return 0 on success, otherwise a negative error value
 449  * @retval #VINE_ERROR_NONE     Successful
 450  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 451  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 452  * @see vine_session_set_discovered_cb()
 453  */
 454 int vine_session_unset_discovered_cb(vine_session_h session);
 455
 456 /**
 457  * @brief Set the service discovery method
 458  * @remarks Default service discovery method is DNS-SD
 459  * @since_tizen 6.5
 460  * @param[in] session The session handle
 461  * @param[in] method The service discovery method
 462  * @return 0 on success, otherwise a negative error value
 463  * @retval #VINE_ERROR_NONE     Successful
 464  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 465  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 466  * @see vine_session_create()
 467  */
 468 int vine_session_set_discovery_method(vine_session_h session, vine_discovery_method_e method);
 469
 470 /**
 471  * @brief Registers a service.
 472  * @remarks @a service can be freed after using this API.
 473  * @remarks Cannot register if a service is already running.
 474  * @remarks If @a iface_name is NULL, all interfaces are used for service registration.
 475  * @since_tizen 6.5
 476  * @param[in] session The session handle
 477  * @param[in] service The service handle
 478  * @param[in] iface_name The interface name
 479  * @return 0 on success, otherwise a negative error value
 480  * @retval #VINE_ERROR_NONE     Successful
 481  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 482  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 483  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 484  * @see vine_session_create()
 485  * @see vine_session_unregister()
 486  */
 487 int vine_session_register(vine_session_h session,
 488         vine_service_h service, const char *iface_name);
 489
 490 /**
 491  * @brief Unregisters a service.
 492  * @since_tizen 6.5
 493  * @param[in] session The session handle
 494  * @return 0 on success, otherwise a negative error value
 495  * @retval #VINE_ERROR_NONE     Successful
 496  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 497  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 498  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 499  * @see vine_session_create()
 500  * @see vine_session_register()
 501  */
 502 int vine_session_unregister(vine_session_h session);
 503
 504 /**
 505  * @brief Starts a service discovery.
 506  * @remarks Cannot discover a service if a service is already running.
 507  * @remarks The length of @a service_type should be less than 63 characters. Dot(.) and comma(,) are not allowed.
 508  * @remarks If @a iface_name is NULL, all interfaces are used for service registration.
 509  * @since_tizen 6.5
 510  * @param[in] session The session handle
 511  * @param[in] service_type The service_type to be discovered
 512  * @param[in] iface_name The interface name
 513  * @return 0 on success, otherwise a negative error value
 514  * @retval #VINE_ERROR_NONE     Successful
 515  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 516  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 517  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 518  * @see vine_session_create()
 519  * @see vine_session_stop_discovery()
 520  */
 521 int vine_session_start_discovery(vine_session_h session,
 522         const char *service_type, const char *iface_name);
 523
 524 /**
 525  * @brief Stops a service discovery
 526  * @since_tizen 6.5
 527  * @param[in] session The session handle
 528  * @return 0 on success, otherwise a negative error value
 529  * @retval #VINE_ERROR_NONE     Successful
 530  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 531  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 532  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 533  * @see vine_session_create()
 534  * @see vine_session_start_discovery()
 535  */
 536 int vine_session_stop_discovery(vine_session_h session);
 537
 538 /**
 539  * @brief Called when an IP address is resolved.
 540  * @remarks @a ip must be released using free().
 541  * @since_tizen 6.5
 542  * @param[in] service The service
 543  * @param[in] ip The IP address
 544  * @param[in] address_family The address familye
 545  * @param[in] user_data The user data passed from the callback registration function
 546  * @see vine_service_resolve_ip()
 547   */
 548 typedef void(*vine_session_ip_resolved_cb)(vine_session_h session, vine_service_h service,
 549         const char *ip, vine_address_family_e address_family, /* availability */
 550         void *user_data);
 551
 552 /**
 553  * @brief Resolves IP addresses for @a service.
 554  * @remarks This API works only for @a service discovered by vine_session_discovered_cb callback
 555  * @since_tizen 6.5
 556  * @param[in] session The session handle
 557  * @param[in] service The service handle
 558  * @param[in] callback The resolved callback
 559  * @param[in] user_data The user data
 560  * @return 0 on success, otherwise a negative error value
 561  * @retval #VINE_ERROR_NONE     Successful
 562  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 563  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 564   */
 565 int vine_session_set_ip_resolved_cb(vine_session_h session,
 566         vine_service_h service, vine_session_ip_resolved_cb callback, void *user_data);
 567
 568 /**
 569  * @brief Stop resolving IP addresses for @a service.
 570  * @remarks This API works only for @a service discovered by vine_session_discovered_cb callback
 571  * @since_tizen 6.5
 572  * @param[in] session The session handle
 573  * @param[in] service The service handle
 574  * @return 0 on success, otherwise a negative error value
 575  * @retval #VINE_ERROR_NONE     Successful
 576  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 577  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 578   */
 579 int vine_session_unset_ip_resolved_cb(vine_session_h session,
 580         vine_service_h service);
 581
 582 /**
 583  * @brief Creates a service.
 584  * @remarks @a service should be released using vine_service_destroy().
 585  * @since_tizen 6.5
 586  * @param[out] service The service handle
 587  * @return 0 on success, otherwise a negative error value
 588  * @retval #VINE_ERROR_NONE     Successful
 589  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 590  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 591  * @see vine_service_destroy()
 592  */
 593 int vine_service_create(vine_service_h *service);
 594
 595 /**
 596  * @brief Destroys a service.
 597  * @since_tizen 6.5
 598  * @param[in] service The service handle
 599  * @return 0 on success, otherwise a negative error value
 600  * @retval #VINE_ERROR_NONE     Successful
 601  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 602  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 603  * @see vine_service_create()
 604  */
 605 int vine_service_destroy(vine_service_h service);
 606
 607 /**
 608  * @brief Clones a service handle.
 609  * @remarks @a cloned should be released using vine_service_destroy().
 610  * @since_tizen 6.5
 611  * @param[in] origin The origin service handle
 612  * @param[out] cloned The cloned service handle
 613  * @return 0 on success, otherwise a negative error value
 614  * @retval #VINE_ERROR_NONE     Successful
 615  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 616  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 617  * @see vine_service_destroy()
 618  */
 619 int vine_service_clone(vine_service_h origin, vine_service_h *cloned);
 620
 621 /**
 622  * @brief Sets the service type for the service. Only for @a service created by vine_service_create().
 623  * @remarks For @a service discovered by vine_session_discovered_cb callback, this API doesn't work.
 624  * @remarks @a service_type should not be NULL.
 625  * @remarks The length of @a service_type should be less than 63 characters. Dot(.) and comma(,) are not allowed.
 626  * @remarks @a service_type can be freed after this API is called.
 627  * @since_tizen 6.5
 628  * @param[in] service The service handle
 629  * @param[in] service_type The service type
 630  * @return 0 on success, otherwise a negative error value
 631  * @retval #VINE_ERROR_NONE     Successful
 632  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 633  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 634  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 635  * @see vine_service_create()
 636  */
 637 int vine_service_set_type(vine_service_h service, const char *service_type);
 638
 639 /**
 640  * @brief Gets the service type for the service.
 641  * @remarks @a service_type must be released using free().
 642  * @since_tizen 6.5
 643  * @param[in] service The service handle
 644  * @param[out] service_type The service type
 645  * @return 0 on success, otherwise a negative error value
 646  * @retval #VINE_ERROR_NONE     Successful
 647  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 648  * @retval #VINE_ERROR_OUT_OF_MEMORY    Out of memory
 649  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 650  * @see vine_service_create()
 651  */
 652 int vine_service_get_type(vine_service_h service, char **service_type);
 653
 654 /**
 655  * @brief Sets the name for the service. Only for @a service created by vine_service_create().
 656  * @remarks For @a service discovered by vine_session_discovered_cb callback, this API doesn't work.
 657  * @remarks @a service_name should not be NULL.
 658  * @remarks The length of @a service_name is limited to 1-63 bytes.
 659  * @remarks @a service_name can be freed after this API is called.
 660  * @since_tizen 6.5
 661  * @param[in] service The service handle
 662  * @param[in] service_name The service name
 663  * @return 0 on success, otherwise a negative error value
 664  * @retval #VINE_ERROR_NONE     Successful
 665  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 666  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 667  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 668   * @see vine_service_create()
 669  */
 670 int vine_service_set_name(vine_service_h service, const char *service_name);
 671
 672 /**
 673  * @brief Gets the name for the service.
 674  * @remarks @a service_name must be released using free().
 675  * @since_tizen 6.5
 676  * @param[in] service The service handle
 677  * @param[out] service_name The service name
 678  * @return 0 on success, otherwise a negative error value
 679  * @retval #VINE_ERROR_NONE     Successful
 680  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 681  * @retval #VINE_ERROR_OUT_OF_MEMORY    Out of memory
 682  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 683  * @see vine_service_create()
 684  */
 685 int vine_service_get_name(vine_service_h service, char **service_name);
 686
 687 /**
 688  * @brief Adds an attribute. Only for @a service created by vine_service_create().
 689  * @remarks For @a service discovered by vine_session_discovered_cb callback, this API doesn't work.
 690  * @since_tizen 6.5
 691  * @remarks @a key is a null-terminated string which is limited to the maximum 9 characters.
 692  * @remarks @a key should consist of ASCII values (0x20-0x7E).
 693  * @remarks @a value can be NULL, which represents an empty string.
 694  * @remarks @a key and @a value will be internally copied, so they can be freed.
 695  * @remarks When DNS-SD is used for service discovery, attributes are converted to TXT records.
 696  *          TXT records generally are limited to less than 100 bytes.
 697  *          Using TXT records larger than 1300 bytes is NOT RECOMMENDED.
 698  *          Reference: http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt
 699  *                      The length of an attribute (key length + value length) is limited to 252.
 700  * @param[in] service The service handle
 701  * @param[in] key The key of attribute
 702  * @param[in] value The value of attribute
 703  * @return 0 on success, otherwise a negative error value
 704  * @retval #VINE_ERROR_NONE     Successful
 705  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 706  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 707  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 708  * @see vine_service_create()
 709  */
 710 int vine_service_add_attribute(vine_service_h service,
 711         const char *key, const char *value);
 712
 713 /**
 714  * @brief Removes an attribute. Only for @a service created by vine_service_create().
 715  * @remarks For @a service discovered by vine_session_discovered_cb callback, this API doesn't work.
 716  * @since_tizen 6.5
 717  * @param[in] service The service handle
 718  * @param[in] key The key of attribute
 719  * @return 0 on success, otherwise a negative error value
 720  * @retval #VINE_ERROR_NONE     Successful
 721  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 722  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 723  * @see vine_service_create()
 724  * @see vine_service_add_attribute()
 725  */
 726 int vine_service_remove_attribute(vine_service_h service, const char *key);
 727
 728 /**
 729  * @brief Called for each attribute for a service
 730  * @remarks @a key and @value are valid only in this function.
 731  * @remarks Each key in @a keys is a null-terminated string which is limited to the maximum 9 characters.
 732  * @remarks Each key in @a keys consist of ASCII values (0x20-0x7E).
 733  * @remarks Each value in @a values can be NULL, which represents an empty string.
 734  * @since_tizen 6.5
 735  * @param[in] key The key
 736  * @param[in] value The value
 737  * @param[in] user_data The user data
 738  * @return @c true to continue with the next iteration of the loop,
 739  *         otherwise @c false to break out of the loop.
 740  * @see vine_service_foreach_attribute()
 741  */
 742 typedef bool(*vine_service_attribute_cb)(
 743         const char *key, const char *value, void *user_data);
 744
 745 /**
 746  * @brief Gets the list of attributes. Each attribute is represented as a <key, value> pair.
 747  * @since_tizen 6.5
 748  * @param[in] service The service handle
 749  * @param[in] callback The callback to call with each attribute
 750  * @param[in] user_data The user data passed to the callback, or NULL
 751  * @return 0 on success, otherwise a negative error value
 752  * @retval #VINE_ERROR_NONE     Successful
 753  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 754  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 755  * @see vine_service_create()
 756  * @see vine_service_attribute_cb
 757  */
 758 int vine_service_foreach_attribute(vine_service_h service,
 759         vine_service_attribute_cb callback, void *user_data);
 760
 761 /**
 762  * @brief Sets the port number. Only for @a service created by vine_service_create().
 763  * @remarks For @a service discovered by vine_session_discovered_cb callback, this API doesn't work.
 764  * @since_tizen 6.5
 765  * @param[in] service The service handle
 766  * @param[in] port The port number for the service
 767  * @return 0 on success, otherwise a negative error value
 768  * @retval #VINE_ERROR_NONE     Successful
 769  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 770  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 771  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 772  * @see vine_service_create()
 773  */
 774 int vine_service_set_port(vine_service_h service, int port);
 775
 776 /**
 777  * @brief Gets the port number.
 778  * @remarks @a port will be 0 if it isn't set up.
 779  * @since_tizen 6.5
 780  * @param[in] service The service handle
 781  * @param[out] port The port number
 782  * @return 0 on success, otherwise a negative error value
 783  * @retval #VINE_ERROR_NONE     Successful
 784  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 785  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 786  * @see vine_service_create()
 787  */
 788 int vine_service_get_port(vine_service_h service, int *port);
 789
 790 /**
 791  * @brief Creates the data path handle.
 792  * @since_tizen 6.5
 793  * @param[in] session The session handle
 794  * @param[in] type The data path type
 795  * @param[out] dp The data path handle
 796  * @return 0 on success, otherwise a negative error value
 797  * @retval #VINE_ERROR_NONE     Successful
 798  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 799  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 800  * @see vine_dp_destroy()
 801  * @see vine_session_create()
 802  */
 803 int vine_dp_create(vine_session_h session, vine_dp_type_e type, vine_dp_h *dp);
 804
 805 /**
 806  * @brief Destroys the data path handle.
 807  * @since_tizen 6.5
 808  * @param[in] dp The data path handle
 809  * @return 0 on success, otherwise a negative error value
 810  * @retval #VINE_ERROR_NONE     Successful
 811  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 812  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 813  * @see vine_dp_create()
 814  */
 815 int vine_dp_destroy(vine_dp_h dp);
 816
 817 /**
 818  * @brief Sets the interface name to use for datapath.
 819  * @remarks If the interface has multiple IP addresses, please set an IP address as @a iface_name.
 820  * @since_tizen 6.5
 821  * @param[in] dp The data path handle
 822  * @param[in] iface_or_ip The interface name or IP address
 823  * @return 0 on success, otherwise a negative error value
 824  * @retval #VINE_ERROR_NONE     Successful
 825  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 826  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 827  * @see vine_dp_create()
 828  */
 829 int vine_dp_set_iface_name(vine_dp_h dp, const char *iface_or_ip);
 830
 831 /**
 832  * @brief Sets the address family.
 833  * @remarks This is ignored when dp type is VINE_DP_TYPE_CLIENT.
 834  * @since_tizen 6.5
 835  * @param[in] dp The data path handle
 836  * @param[in] iface_name The interface name
 837  * @return 0 on success, otherwise a negative error value
 838  * @retval #VINE_ERROR_NONE     Successful
 839  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 840  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 841  * @see vine_dp_create()
 842  */
 843 int vine_dp_set_address_family(vine_dp_h dp, vine_address_family_e addr_family);
 844
 845 /**
 846  * @brief Sets the remote IP address.
 847  * @since_tizen 6.5
 848  * @param[in] dp The data path handle
 849  * @param[in] addr_family The address family
 850  * @param[in] ip The remote IP address
 851  * @return 0 on success, otherwise a negative error value
 852  * @retval #VINE_ERROR_NONE     Successful
 853  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 854  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 855  * @see vine_dp_create()
 856  */
 857 int vine_dp_set_remote_ip(vine_dp_h dp, vine_address_family_e addr_family, const char *ip);
 858
 859 /**
 860  * @brief Sets the port.
 861  * @remarks @a port is a remote server port if @a dp's type is VINE_DP_TYPE_CLIENT. \
 862  *          Otherwise, @a port is a listen port. \
 863  *          If it is a listen port, you can set it to 0 so that a random port is picked by the kernel.
 864  * @since_tizen 6.5
 865  * @param[in] dp The data path handle
 866  * @param[in] port The port
 867  * @return 0 on success, otherwise a negative error value
 868  * @retval #VINE_ERROR_NONE     Successful
 869  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 870  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 871  * @see vine_dp_create()
 872  */
 873 int vine_dp_set_port(vine_dp_h dp, int port);
 874
 875 /**
 876  * @brief Gets the port.
 877  * @since_tizen 6.5
 878  * @param[in] dp The data path handle
 879  * @param[out] port The port
 880  * @return 0 on success, otherwise a negative error value
 881  * @retval #VINE_ERROR_NONE     Successful
 882  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 883  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 884  * @see vine_dp_create()
 885  */
 886 int vine_dp_get_port(vine_dp_h dp, int *port);
 887
 888 /**
 889  * @brief Sets the topic. Only for Publish-Subscribe type.
 890  * @remarks The length of @a topic should be less than 63 characters.
 891  * @since_tizen 6.5
 892  * @param[in] dp The data path handle
 893  * @param[in] topic The topic
 894  * @return 0 on success, otherwise a negative error value
 895  * @retval #VINE_ERROR_NONE     Successful
 896  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 897  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 898  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 899  * @see vine_dp_create()
 900  */
 901 int vine_dp_set_topic(vine_dp_h dp, const char *topic);
 902
 903 /**
 904  * @brief Sets the maximum number of connections.
 905  * @remarks This doesn't affect the client dp or the opened dp.
 906  * @since_tizen 6.5
 907  * @param[in] dp The datapath handle
 908  * @param[in] max_conn The maximum number of connections
 909  * @return 0 on success, otherwise a negative error value
 910  * @retval #VINE_ERROR_NONE     Successful
 911  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 912  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 913  * @see vine_initialize()
 914  */
 915 int vine_dp_set_max_connections(vine_dp_h dp, int max_conn);
 916
 917 /**
 918  * @brief Sets the security information.
 919  * @remarks Releasing @a security after this function does not affect the operation of the datapath\
 920  *          because @a security is copied internally.
 921  * @since_tizen 6.5
 922  * @param[in] dp The data path handle
 923  * @param[in] security The security handle
 924  * @return 0 on success, otherwise a negative error value
 925  * @retval #VINE_ERROR_NONE     Successful
 926  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 927  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 928  * @see vine_dp_create()
 929  * @see vine_security_create()
 930  */
 931 int vine_dp_set_security(vine_dp_h dp, vine_security_h security);
 932
 933 /**
 934  * @brief Called whenever the peer is accepted.
 935  * @remarks @a dp must be released by vine_dp_destroy() if you don't use it anymore.
 936  * @since_tizen 6.5
 937  * @param[in] dp The data path handle
 938  * @param[in] accepted_dp The data path handle for accepted peer
 939  * @param[in] user_data The user data passed from the callback registration function
 940  * @see vine_dp_set_accepted_cb()
 941  */
 942 typedef void(*vine_dp_accepted_cb)(vine_dp_h dp, vine_dp_h accepted_dp, void *user_data);
 943
 944 /**
 945  * @brief Sets accepted callback called when peer is accepted.
 946  * @since_tizen 6.5
 947  * @param[in] dp The data path handle
 948  * @param[in] callback The accepted callback
 949  * @param[in] user_data The user data
 950  * @return 0 on success, otherwise a negative error value
 951  * @retval #VINE_ERROR_NONE     Successful
 952  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 953  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 954  * @see vine_dp_create()
 955  * @see vine_dp_unset_accepted_cb()
 956  */
 957 int vine_dp_set_accepted_cb(vine_dp_h dp, vine_dp_accepted_cb callback, void *user_data);
 958
 959 /**
 960  * @brief Unsets accepted callback.
 961  * @since_tizen 6.5
 962  * @param[in] dp The data path handle
 963  * @return 0 on success, otherwise a negative error value
 964  * @retval #VINE_ERROR_NONE     Successful
 965  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 966  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 967  * @see vine_dp_create()
 968  * @see vine_dp_set_accepted_cb()
 969  */
 970 int vine_dp_unset_accepted_cb(vine_dp_h dp);
 971
 972 /**
 973  * @brief Called when datapath is terminated by peer.
 974  * @since_tizen 6.5
 975  * @param[in] dp The terminated datapath
 976  * @param[in] user_data The user data passed from the callback registration function
 977  * @see vine_dp_set_terminated_cb()
 978  * @see vine_dp_unset_terminated_cb()
 979  */
 980 typedef void(*vine_dp_terminated_cb)(vine_dp_h dp, void *user_data);
 981
 982 /**
 983  * @brief Registers datapath terminated callback called when datapath is closed by peer.
 984  * @since_tizen 6.5
 985  * @param[in] dp The datapath handle
 986  * @param[in] callback The terminated callback
 987  * @param[in] user_data The user data
 988  * @return 0 on success, otherwise a negative error value
 989  * @retval #VINE_ERROR_NONE     Successful
 990  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 991  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 992  * @see vine_session_unset_data_path_terminated_cb()
 993  */
 994 int vine_dp_set_terminated_cb(vine_dp_h dp, vine_dp_terminated_cb callback, void *user_data);
 995
 996 /**
 997  * @brief Unregisters datapath terminated callback.
 998  * @since_tizen 6.5
 999  * @param[in] dp The datapath handle
1000  * @return 0 on success, otherwise a negative error value
1001  * @retval #VINE_ERROR_NONE     Successful
1002  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1003  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1004  * @see vine_session_set_data_path_terminated_cb()
1005  */
1006 int vine_dp_unset_terminated_cb(vine_dp_h dp);
1007
1008 /**
1009  * @brief Called when @a dp is opened.
1010  * @since_tizen 6.5
1011  * @param[in] dp The data path handle
1012  * @param[in] user_data The user data passed from vine_dp_open()
1013  * @see vine_dp_open()
1014  */
1015 typedef void (*vine_dp_opened_cb)(vine_dp_h dp, vine_error_e result, void *user_data);
1016
1017 /**
1018  * @brief Opens a datapath.
1019  * @remarks This works depending on the type of datapath differently.
1020  * If @a dp is a server, a listen port is opened.
1021  * If @a dp is a client, it tries to connect to a server.
1022  * If @a dp is for Publish-Subscribe, it joins to a service which has the same topic.
1023  * @since_tizen 6.5
1024  * @param[in] dp The data path handle
1025  * @param[in] callback The callback to be called
1026  * @param[in] user_data The user data passed to the callback function
1027  * @return 0 on success, otherwise a negative error value
1028  * @retval #VINE_ERROR_NONE     Successful
1029  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1030  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1031  * @see vine_dp_create()
1032  * @see vine_dp_close()
1033  */
1034 int vine_dp_open(vine_dp_h dp, vine_dp_opened_cb callback, void *user_data);
1035
1036 /**
1037  * @brief Closes the datapath.
1038  * @remarks The network connections with remote peers will be terminated.
1039  * @since_tizen 6.5
1040  * @param[in] dp The datapath handle
1041  * @return 0 on success, otherwise a negative error value
1042  * @retval #VINE_ERROR_NONE     Successful
1043  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1044  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1045  * @see vine_dp_open()
1046  */
1047 int vine_dp_close(vine_dp_h dp);
1048
1049 /**
1050  * @brief Sends a message through the datapath.
1051  * @since_tizen 6.5
1052  * @remarks @buf will be sent to a peer when writable state.
1053  * @param[in] dp The datapath handle
1054  * @param[in] buf The message to be written
1055  * @param[in] len The size in bytes to be written
1056  * @return 0 on success, otherwise a negative error value
1057  * @retval #VINE_ERROR_NONE     Successful
1058  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1059  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1060  * @see vine_dp_create()
1061  */
1062 int vine_dp_send(vine_dp_h dp, unsigned char *buf, size_t len);
1063
1064 /**
1065  * @brief Reads up to @buf_len bytes from a @datapath into @buf.
1066  * @since_tizen 6.5
1067  * @remarks This function can be called in vine_dp_received_cb() only.\
1068  *  If @buf_len is larger than @received_len of vine_dp_received_cb, \
1069  *  unexpected data can be read.
1070  * @param[in] dp The datapath handle
1071  * @param[in] buf The buffer to be filled out
1072  * @param[in] buf_len The buffer size
1073  * @param[out] read_len The size in bytes to be read
1074  * @return 0 on success, otherwise a negative error value
1075  * @retval #VINE_ERROR_NONE     Successful
1076  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1077  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1078  * @see vine_dp_create()
1079  * @see vine_dp_set_received_cb()
1080  */
1081 int vine_dp_recv(vine_dp_h dp,
1082                 unsigned char *buf, size_t buf_len, size_t *read_len);
1083
1084 /**
1085  * @brief Called when readable state.
1086  * @since_tizen 6.5
1087  * @remarks vine_dp_recv can be called in this callback
1088  * @param[in] dp  The datapath handle
1089  * @param[in] received_len The number of bytes transferred
1090  * @param[in] user_data The user data passed from the callback registration function
1091  * @see vine_dp_set_received_cb()
1092  * @see vine_dp_unset_received_cb()
1093  * @see vine_dp_read()
1094  */
1095 typedef void(*vine_dp_received_cb)(vine_dp_h dp, size_t received_len, void *user_data);
1096
1097 /**
1098  * @brief Registers the callback called when a message is received from a peer.
1099  * @since_tizen 6.5
1100  * @param[in] dp The datapath handle
1101  * @param[in] callback The callback function to be called
1102  * @param[in] user_data The user data passed to the callback function
1103  * @return 0 on success, otherwise a negative error value
1104  * @retval #VINE_ERROR_NONE     Successful
1105  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1106  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1107  * @see vine_dp_create()
1108  * @see vine_dp_unset_received_cb()
1109  */
1110 int vine_dp_set_received_cb(vine_dp_h dp, vine_dp_received_cb callback, void *user_data);
1111
1112 /**
1113  * @brief Unregisters the callback called when a message is received from a peer.
1114  * @since_tizen 6.5
1115  * @param[in] dp The datapath handle
1116  * @return 0 on success, otherwise a negative error value
1117  * @retval #VINE_ERROR_NONE     Successful
1118  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1119  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1120  * @see vine_initialize()
1121  * @see vine_dp_set_received_cb()
1122  */
1123 int vine_dp_unset_received_cb(vine_dp_h dp);
1124
1125 /**
1126  * @brief Creates a security configuration.
1127  * @since_tizen 6.5
1128  * @param[out] security The security handle
1129  * @return 0 on success, otherwise a negative error value
1130  * @retval #VINE_ERROR_NONE     Successful
1131  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1132  * @retval #VINE_ERROR_OUT_OF_MEMORY    Out of memory
1133  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1134  * @see vine_security_destroy()
1135  */
1136 int vine_security_create(vine_security_h *security);
1137
1138 /**
1139  * @brief Destroys a security configuration.
1140  * @since_tizen 6.5
1141  * @param[in] security The security handle
1142  * @return 0 on success, otherwise a negative error value
1143  * @retval #VINE_ERROR_NONE     Successful
1144  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1145  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1146  * @see vine_security_create()
1147  */
1148 int vine_security_destroy(vine_security_h security);
1149
1150 /**
1151  * @brief Sets a security type.
1152  * @since_tizen 6.5
1153  * @param[in] security The security handle
1154  * @param[in] type      The security type
1155  * @return 0 on success, otherwise a negative error value
1156  * @retval #VINE_ERROR_NONE     Successful
1157  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1158  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1159  * @see vine_security_get_type()
1160  */
1161 int vine_security_set_type(vine_security_h security, vine_security_type_e type);
1162
1163 /**
1164  * @brief Gets a security type.
1165  * @since_tizen 6.5
1166  * @param[in] security The security handle
1167  * @param[out] type The security type
1168  * @return 0 on success, otherwise a negative error value
1169  * @retval #VINE_ERROR_NONE     Successful
1170  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1171  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1172  * @see vine_security_set_type()
1173  */
1174 int vine_security_get_type(vine_security_h security, vine_security_type_e *type);
1175
1176 /**
1177  * @brief Sets TLS version range.
1178  * @remarks SSLv2 and SSLv3 are not supported because both versions were proven to be insecure.
1179  * @since_tizen 6.5
1180  * @param[in] security The security handle
1181  * @param[in] version The TLS version
1182  * @return 0 on success, otherwise a negative error value
1183  * @retval #VINE_ERROR_NONE     Successful
1184  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1185  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1186  * @see vine_security_get_tls_version()
1187  * @see vine_security_set_type()
1188  */
1189 int vine_security_set_tls_version(vine_security_h security, vine_security_tls_version_e version);
1190
1191 /**
1192  * @brief Gets TLS version range.
1193  * @since_tizen 6.5
1194  * @param[in] security The security handle
1195  * @param[in] version The TLS version
1196  * @return 0 on success, otherwise a negative error value
1197  * @retval #VINE_ERROR_NONE     Successful
1198  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1199  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1200  * @see vine_security_set_tls_version()
1201  * @see vine_security_set_type()
1202  */
1203 int vine_security_get_tls_version(vine_security_h security, vine_security_tls_version_e *version);
1204
1205 /**
1206  * @brief Sets combination of verification flags.
1207  * @since_tizen 6.5
1208  * @param[in] security The security handle
1209  * @param[in] flags The bitwise set of one or more of @a vine_security_verification_flag_e
1210  * @return 0 on success, otherwise a negative error value
1211  * @retval #VINE_ERROR_NONE     Successful
1212  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1213  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1214  * @see vine_security_get_verification_flags()
1215  * @see vine_security_set_type()
1216  */
1217 int vine_security_set_verification_flags(vine_security_h security, int flags);
1218
1219 /**
1220  * @brief Gets combination of verification flags.
1221  * @since_tizen 6.5
1222  * @param[in] security The security handle
1223  * @param[out] flags The bitwise set of one or more of @a vine_security_verification_flag_e
1224  * @return 0 on success, otherwise a negative error value
1225  * @retval #VINE_ERROR_NONE     Successful
1226  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1227  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1228  * @see vine_security_set_verification_flags()
1229  */
1230 int vine_security_get_verification_flags(vine_security_h security, int *flags);
1231
1232 /**
1233  * @brief Sets CA(Certificate Authority) certificates path.
1234  * @remarks The certificates in @ca_path are used when verifying the peer.
1235  * @since_tizen 6.5
1236  * @param[in] security The security handle
1237  * @param[in] ca_path The directory holding CA certificates
1238  * @return 0 on success, otherwise a negative error value
1239  * @retval #VINE_ERROR_NONE     Successful
1240  * @retval #VINE_ERROR_INVALID_PARAMTER Invalid parameter
1241  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1242  * @see vine_security_get_ca_path()
1243  */
1244 int vine_security_set_ca_path(vine_security_h security, const char *ca_path);
1245
1246 /**
1247  * @brief Gets CA(Certificate Authority) certificates path.
1248  * @remarks @a ca_path must be released using free().
1249  * @since_tizen 6.5
1250  * @param[in] security The security handle
1251  * @param[out] ca_path The directory holding CA certificates
1252  * @return 0 on success, otherwise a negative error value
1253  * @retval #VINE_ERROR_NONE     Successful
1254  * @retval #VINE_ERROR_INVALID_PARAMTER Invalid parameter
1255  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1256  * @see vine_security_set_ca_path()
1257  */
1258 int vine_security_get_ca_path(vine_security_h security, char **ca_path);
1259
1260 /**
1261  * @brief Sets certificate path.
1262  * @remarks The certificate is transfered to peer during TLS/SSL handshaking.
1263  * @since_tizen 6.5
1264  * @param[in] security The security handle.
1265  * @param[in] cert_path The certificate path.
1266  * @return 0 on success, otherwise a negative error value
1267  * @retval #VINE_ERROR_NONE     Successful
1268  * @retval #VINE_ERROR_INVALID_PARAMTER Invalid parameter
1269  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1270  * @see vine_security_set_type()
1271  * @see vine_security_set_private_key()
1272  */
1273 int vine_security_set_cert_path(vine_security_h security, const char *cert_path);
1274
1275 /**
1276  * @brief Gets certificate path.
1277  * @remarks @a cert_path must be released using free().
1278  * @since_tizen 6.5
1279  * @param[in] security The security handle.
1280  * @param[out] cert_path The certificate path.
1281  * @return 0 on success, otherwise a negative error value
1282  * @retval #VINE_ERROR_NONE     Successful
1283  * @retval #VINE_ERROR_INVALID_PARAMTER Invalid parameter
1284  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1285  * @see vine_security_set_cert_path()
1286  */
1287 int vine_security_get_cert_path(vine_security_h security, char **cert_path);
1288
1289 /**
1290  * @brief Sets key path for the certificate.
1291  * @since_tizen 6.5
1292  * @param[in] security The security handle.
1293  * @param[in] key_path The key path.
1294  * @return 0 on success, otherwise a negative error value
1295  * @retval #VINE_ERROR_NONE     Successful
1296  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1297  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1298  * @see vine_security_set_type()
1299  * @see vine_security_set_cert_path()
1300  */
1301 int vine_security_set_private_key(vine_security_h security, const char *key_path);
1302
1303 /**
1304  * @brief Gets key path for the certificate.
1305  * @remarks @a key_path must be released using free().
1306  * @since_tizen 6.5
1307  * @param[in] security The security handle.
1308  * @param[out] key_path The key path.
1309  * @return 0 on success, otherwise a negative error value
1310  * @retval #VINE_ERROR_NONE     Successful
1311  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1312  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1313  * @see vine_security_set_private_key()
1314  */
1315 int vine_security_get_private_key(vine_security_h security, char **key_path);
1316
1317 /**
1318  * @brief Sets preshared key to verify peer.
1319  * @remarks The @psk is exchanged over a websocket connection.
1320  * @since_tizen 6.5
1321  * @param[in] security The security handle.
1322  * @param[in] psk The preshared key
1323  * @return 0 on success, otherwise a negative error value
1324  * @retval #VINE_ERROR_NONE     Successful
1325  * @retval #VINE_ERROR_INVALID_PARAMTER Invalid parameter
1326  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1327  * @see vine_security_get_psk()
1328  */
1329 int vine_security_set_psk(vine_security_h security, const char *psk);
1330
1331 /**
1332  * @brief Gets preshared key to verify peer.
1333  * @remarks @a psk must be released using free().
1334  * @since_tizen 6.5
1335  * @param[in] security The security handle.
1336  * @param[out] psk The preshared key
1337  * @return 0 on success, otherwise a negative error value
1338  * @retval #VINE_ERROR_NONE     Successful
1339  * @retval #VINE_ERROR_INVALID_PARAMTER Invalid parameter
1340  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1341  * @see vine_security_set_psk()
1342  */
1343 int vine_security_get_psk(vine_security_h security, char **psk);
1344
1345 /**
1346  * @}
1347  */
1348
1349 #ifdef __cplusplus
1350 }
1351 #endif
1352
1353 #endif /* __VINE_H__ */
1354