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  * @since_tizen 6.5
 418  * @param[in] session The session handle
 419  * @param[in] discovered_service The discovered service
 420  * @param[in] state The availability of the discovered service
 421  * @param[in] user_data The user data passed from the callback registration function
 422  * @see vine_session_set_discovered_cb()
 423  * @see vine_session_unset_discovered_cb()
 424  */
 425 typedef void(*vine_session_discovered_cb)(vine_session_h session,
 426                 vine_service_h discovered_service, vine_service_state_e state, void *user_data);
 427
 428 /**
 429  * @brief Registers discovered callback called when service is discovered.
 430  * @since_tizen 6.5
 431  * @param[in] session The session handle
 432  * @param[in] callback The discovered callback
 433  * @param[in] user_data The user data
 434  * @return 0 on success, otherwise a negative error value
 435  * @retval #VINE_ERROR_NONE     Successful
 436  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 437  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 438  * @see vine_session_unset_discovered_cb()
 439  */
 440 int vine_session_set_discovered_cb(vine_session_h session,
 441                 vine_session_discovered_cb callback, void *user_data);
 442
 443 /**
 444  * @brief Unregisters discovered callback.
 445  * @since_tizen 6.5
 446  * @param[in] session The session handle
 447  * @return 0 on success, otherwise a negative error value
 448  * @retval #VINE_ERROR_NONE     Successful
 449  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 450  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 451  * @see vine_session_set_discovered_cb()
 452  */
 453 int vine_session_unset_discovered_cb(vine_session_h session);
 454
 455 /**
 456  * @brief Set the service discovery method
 457  * @remarks Default service discovery method is DNS-SD
 458  * @since_tizen 6.5
 459  * @param[in] session The session handle
 460  * @param[in] method The service discovery method
 461  * @return 0 on success, otherwise a negative error value
 462  * @retval #VINE_ERROR_NONE     Successful
 463  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 464  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 465  * @see vine_session_create()
 466  */
 467 int vine_session_set_discovery_method(vine_session_h session, vine_discovery_method_e method);
 468
 469 /**
 470  * @brief Registers a service.
 471  * @remarks @a service can be freed after using this API.
 472  * @remarks Cannot register if a service is already running.
 473  * @remarks If @a iface_name is NULL, all interfaces are used for service registration.
 474  * @since_tizen 6.5
 475  * @param[in] session The session handle
 476  * @param[in] service The service handle
 477  * @param[in] iface_name The interface name
 478  * @return 0 on success, otherwise a negative error value
 479  * @retval #VINE_ERROR_NONE     Successful
 480  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 481  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 482  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 483  * @see vine_session_create()
 484  * @see vine_session_unregister()
 485  */
 486 int vine_session_register(vine_session_h session,
 487         vine_service_h service, const char *iface_name);
 488
 489 /**
 490  * @brief Unregisters a service.
 491  * @since_tizen 6.5
 492  * @param[in] session The session handle
 493  * @return 0 on success, otherwise a negative error value
 494  * @retval #VINE_ERROR_NONE     Successful
 495  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 496  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 497  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 498  * @see vine_session_create()
 499  * @see vine_session_register()
 500  */
 501 int vine_session_unregister(vine_session_h session);
 502
 503 /**
 504  * @brief Starts a service discovery.
 505  * @remarks Cannot discover a service if a service is already running.
 506  * @remarks The length of @a service_type should be less than 63 characters. Dot(.) and comma(,) are not allowed.
 507  * @remarks If @a iface_name is NULL, all interfaces are used for service registration.
 508  * @since_tizen 6.5
 509  * @param[in] session The session handle
 510  * @param[in] service_type The service_type to be discovered
 511  * @param[in] iface_name The interface name
 512  * @return 0 on success, otherwise a negative error value
 513  * @retval #VINE_ERROR_NONE     Successful
 514  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 515  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 516  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 517  * @see vine_session_create()
 518  * @see vine_session_stop_discovery()
 519  */
 520 int vine_session_start_discovery(vine_session_h session,
 521         const char *service_type, const char *iface_name);
 522
 523 /**
 524  * @brief Stops a service discovery
 525  * @since_tizen 6.5
 526  * @param[in] session The session handle
 527  * @return 0 on success, otherwise a negative error value
 528  * @retval #VINE_ERROR_NONE     Successful
 529  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 530  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 531  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 532  * @see vine_session_create()
 533  * @see vine_session_start_discovery()
 534  */
 535 int vine_session_stop_discovery(vine_session_h session);
 536
 537 /**
 538  * @brief Called when an IP address is resolved.
 539  * @remarks @a ip must be released using free().
 540  * @since_tizen 6.5
 541  * @param[in] service The service
 542  * @param[in] ip The IP address
 543  * @param[in] address_family The address familye
 544  * @param[in] user_data The user data passed from the callback registration function
 545  * @see vine_service_resolve_ip()
 546   */
 547 typedef void(*vine_session_ip_resolved_cb)(vine_session_h session, vine_service_h service,
 548         const char *ip, vine_address_family_e address_family, /* availability */
 549         void *user_data);
 550
 551 /**
 552  * @brief Resolves IP addresses for @a service.
 553  * @remarks This API works only for @a service discovered by vine_session_discovered_cb callback
 554  * @since_tizen 6.5
 555  * @param[in] session The session handle
 556  * @param[in] service The service handle
 557  * @param[in] callback The resolved callback
 558  * @param[in] user_data The user data
 559  * @return 0 on success, otherwise a negative error value
 560  * @retval #VINE_ERROR_NONE     Successful
 561  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 562  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 563   */
 564 int vine_session_set_ip_resolved_cb(vine_session_h session,
 565         vine_service_h service, vine_session_ip_resolved_cb callback, void *user_data);
 566
 567 /**
 568  * @brief Stop resolving IP addresses for @a service.
 569  * @remarks This API works only for @a service discovered by vine_session_discovered_cb callback
 570  * @since_tizen 6.5
 571  * @param[in] session The session handle
 572  * @param[in] service The service handle
 573  * @return 0 on success, otherwise a negative error value
 574  * @retval #VINE_ERROR_NONE     Successful
 575  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 576  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 577   */
 578 int vine_session_unset_ip_resolved_cb(vine_session_h session,
 579         vine_service_h service);
 580
 581 /**
 582  * @brief Creates a service.
 583  * @remarks @a service should be released using vine_service_destroy().
 584  * @since_tizen 6.5
 585  * @param[out] service The service handle
 586  * @return 0 on success, otherwise a negative error value
 587  * @retval #VINE_ERROR_NONE     Successful
 588  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 589  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 590  * @see vine_service_destroy()
 591  */
 592 int vine_service_create(vine_service_h *service);
 593
 594 /**
 595  * @brief Destroys a service.
 596  * @since_tizen 6.5
 597  * @param[in] service The service handle
 598  * @return 0 on success, otherwise a negative error value
 599  * @retval #VINE_ERROR_NONE     Successful
 600  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 601  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 602  * @see vine_service_create()
 603  */
 604 int vine_service_destroy(vine_service_h service);
 605
 606 /**
 607  * @brief Clones a service handle.
 608  * @remarks @a cloned should be released using vine_service_destroy().
 609  * @since_tizen 6.5
 610  * @param[in] origin The origin service handle
 611  * @param[out] cloned The cloned service handle
 612  * @return 0 on success, otherwise a negative error value
 613  * @retval #VINE_ERROR_NONE     Successful
 614  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 615  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 616  * @see vine_service_destroy()
 617  */
 618 int vine_service_clone(vine_service_h origin, vine_service_h *cloned);
 619
 620 /**
 621  * @brief Sets the service type for the service. Only for @a service created by vine_service_create().
 622  * @remarks For @a service discovered by vine_session_discovered_cb callback, this API doesn't work.
 623  * @remarks @a service_type should not be NULL.
 624  * @remarks The length of @a service_type should be less than 63 characters. Dot(.) and comma(,) are not allowed.
 625  * @remarks @a service_type can be freed after this API is called.
 626  * @since_tizen 6.5
 627  * @param[in] service The service handle
 628  * @param[in] service_type The service type
 629  * @return 0 on success, otherwise a negative error value
 630  * @retval #VINE_ERROR_NONE     Successful
 631  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 632  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 633  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 634  * @see vine_service_create()
 635  */
 636 int vine_service_set_type(vine_service_h service, const char *service_type);
 637
 638 /**
 639  * @brief Gets the service type for the service.
 640  * @remarks @a service_type must be released using free().
 641  * @since_tizen 6.5
 642  * @param[in] service The service handle
 643  * @param[out] service_type The service type
 644  * @return 0 on success, otherwise a negative error value
 645  * @retval #VINE_ERROR_NONE     Successful
 646  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 647  * @retval #VINE_ERROR_OUT_OF_MEMORY    Out of memory
 648  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 649  * @see vine_service_create()
 650  */
 651 int vine_service_get_type(vine_service_h service, char **service_type);
 652
 653 /**
 654  * @brief Sets the name for the service. Only for @a service created by vine_service_create().
 655  * @remarks For @a service discovered by vine_session_discovered_cb callback, this API doesn't work.
 656  * @remarks @a service_name should not be NULL.
 657  * @remarks The length of @a service_name is limited to 1-63 bytes.
 658  * @remarks @a service_name can be freed after this API is called.
 659  * @since_tizen 6.5
 660  * @param[in] service The service handle
 661  * @param[in] service_name The service name
 662  * @return 0 on success, otherwise a negative error value
 663  * @retval #VINE_ERROR_NONE     Successful
 664  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 665  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 666  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 667   * @see vine_service_create()
 668  */
 669 int vine_service_set_name(vine_service_h service, const char *service_name);
 670
 671 /**
 672  * @brief Gets the name for the service.
 673  * @remarks @a service_name must be released using free().
 674  * @since_tizen 6.5
 675  * @param[in] service The service handle
 676  * @param[out] service_name The service name
 677  * @return 0 on success, otherwise a negative error value
 678  * @retval #VINE_ERROR_NONE     Successful
 679  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 680  * @retval #VINE_ERROR_OUT_OF_MEMORY    Out of memory
 681  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 682  * @see vine_service_create()
 683  */
 684 int vine_service_get_name(vine_service_h service, char **service_name);
 685
 686 /**
 687  * @brief Adds an attribute. Only for @a service created by vine_service_create().
 688  * @remarks For @a service discovered by vine_session_discovered_cb callback, this API doesn't work.
 689  * @since_tizen 6.5
 690  * @remarks @a key is a null-terminated string which is limited to the maximum 9 characters.
 691  * @remarks @a key should consist of ASCII values (0x20-0x7E).
 692  * @remarks @a value can be NULL, which represents an empty string.
 693  * @remarks @a key and @a value will be internally copied, so they can be freed.
 694  * @remarks When DNS-SD is used for service discovery, attributes are converted to TXT records.
 695  *          TXT records generally are limited to less than 100 bytes.
 696  *          Using TXT records larger than 1300 bytes is NOT RECOMMENDED.
 697  *          Reference: http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt
 698  *                      The length of an attribute (key length + value length) is limited to 252.
 699  * @param[in] service The service handle
 700  * @param[in] key The key of attribute
 701  * @param[in] value The value of attribute
 702  * @return 0 on success, otherwise a negative error value
 703  * @retval #VINE_ERROR_NONE     Successful
 704  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 705  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 706  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 707  * @see vine_service_create()
 708  */
 709 int vine_service_add_attribute(vine_service_h service,
 710         const char *key, const char *value);
 711
 712 /**
 713  * @brief Removes an attribute. Only for @a service created by vine_service_create().
 714  * @remarks For @a service discovered by vine_session_discovered_cb callback, this API doesn't work.
 715  * @since_tizen 6.5
 716  * @param[in] service The service handle
 717  * @param[in] key The key of attribute
 718  * @return 0 on success, otherwise a negative error value
 719  * @retval #VINE_ERROR_NONE     Successful
 720  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 721  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 722  * @see vine_service_create()
 723  * @see vine_service_add_attribute()
 724  */
 725 int vine_service_remove_attribute(vine_service_h service, const char *key);
 726
 727 /**
 728  * @brief Called for each attribute for a service
 729  * @remarks @a key and @value are valid only in this function.
 730  * @remarks Each key in @a keys is a null-terminated string which is limited to the maximum 9 characters.
 731  * @remarks Each key in @a keys consist of ASCII values (0x20-0x7E).
 732  * @remarks Each value in @a values can be NULL, which represents an empty string.
 733  * @since_tizen 6.5
 734  * @param[in] key The key
 735  * @param[in] value The value
 736  * @param[in] user_data The user data
 737  * @return @c true to continue with the next iteration of the loop,
 738  *         otherwise @c false to break out of the loop.
 739  * @see vine_service_foreach_attribute()
 740  */
 741 typedef bool(*vine_service_attribute_cb)(
 742         const char *key, const char *value, void *user_data);
 743
 744 /**
 745  * @brief Gets the list of attributes. Each attribute is represented as a <key, value> pair.
 746  * @since_tizen 6.5
 747  * @param[in] service The service handle
 748  * @param[in] callback The callback to call with each attribute
 749  * @param[in] user_data The user data passed to the callback, or NULL
 750  * @return 0 on success, otherwise a negative error value
 751  * @retval #VINE_ERROR_NONE     Successful
 752  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 753  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 754  * @see vine_service_create()
 755  * @see vine_service_attribute_cb
 756  */
 757 int vine_service_foreach_attribute(vine_service_h service,
 758         vine_service_attribute_cb callback, void *user_data);
 759
 760 /**
 761  * @brief Sets the port number. Only for @a service created by vine_service_create().
 762  * @remarks For @a service discovered by vine_session_discovered_cb callback, this API doesn't work.
 763  * @since_tizen 6.5
 764  * @param[in] service The service handle
 765  * @param[in] port The port number for the service
 766  * @return 0 on success, otherwise a negative error value
 767  * @retval #VINE_ERROR_NONE     Successful
 768  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 769  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 770  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 771  * @see vine_service_create()
 772  */
 773 int vine_service_set_port(vine_service_h service, int port);
 774
 775 /**
 776  * @brief Gets the port number.
 777  * @remarks @a port will be 0 if it isn't set up.
 778  * @since_tizen 6.5
 779  * @param[in] service The service handle
 780  * @param[out] port The port number
 781  * @return 0 on success, otherwise a negative error value
 782  * @retval #VINE_ERROR_NONE     Successful
 783  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 784  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 785  * @see vine_service_create()
 786  */
 787 int vine_service_get_port(vine_service_h service, int *port);
 788
 789 /**
 790  * @brief Creates the data path handle.
 791  * @since_tizen 6.5
 792  * @param[in] session The session handle
 793  * @param[in] type The data path type
 794  * @param[out] dp The data path handle
 795  * @return 0 on success, otherwise a negative error value
 796  * @retval #VINE_ERROR_NONE     Successful
 797  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 798  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 799  * @see vine_dp_destroy()
 800  * @see vine_session_create()
 801  */
 802 int vine_dp_create(vine_session_h session, vine_dp_type_e type, vine_dp_h *dp);
 803
 804 /**
 805  * @brief Destroys the data path handle.
 806  * @since_tizen 6.5
 807  * @param[in] dp The data path handle
 808  * @return 0 on success, otherwise a negative error value
 809  * @retval #VINE_ERROR_NONE     Successful
 810  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 811  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 812  * @see vine_dp_create()
 813  */
 814 int vine_dp_destroy(vine_dp_h dp);
 815
 816 /**
 817  * @brief Sets the interface name to use for datapath.
 818  * @remarks If the interface has multiple IP addresses, please set an IP address as @a iface_name.
 819  * @since_tizen 6.5
 820  * @param[in] dp The data path handle
 821  * @param[in] iface_or_ip The interface name or IP address
 822  * @return 0 on success, otherwise a negative error value
 823  * @retval #VINE_ERROR_NONE     Successful
 824  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 825  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 826  * @see vine_dp_create()
 827  */
 828 int vine_dp_set_iface_name(vine_dp_h dp, const char *iface_or_ip);
 829
 830 /**
 831  * @brief Sets the address family.
 832  * @remarks This is ignored when dp type is VINE_DP_TYPE_CLIENT.
 833  * @since_tizen 6.5
 834  * @param[in] dp The data path handle
 835  * @param[in] iface_name The interface name
 836  * @return 0 on success, otherwise a negative error value
 837  * @retval #VINE_ERROR_NONE     Successful
 838  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 839  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 840  * @see vine_dp_create()
 841  */
 842 int vine_dp_set_address_family(vine_dp_h dp, vine_address_family_e addr_family);
 843
 844 /**
 845  * @brief Sets the remote IP address.
 846  * @since_tizen 6.5
 847  * @param[in] dp The data path handle
 848  * @param[in] addr_family The address family
 849  * @param[in] ip The remote IP address
 850  * @return 0 on success, otherwise a negative error value
 851  * @retval #VINE_ERROR_NONE     Successful
 852  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 853  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 854  * @see vine_dp_create()
 855  */
 856 int vine_dp_set_remote_ip(vine_dp_h dp, vine_address_family_e addr_family, const char *ip);
 857
 858 /**
 859  * @brief Sets the port.
 860  * @remarks @a port is a remote server port if @a dp's type is VINE_DP_TYPE_CLIENT. \
 861  *          Otherwise, @a port is a listen port. \
 862  *          If it is a listen port, you can set it to 0 so that a random port is picked by the kernel.
 863  * @since_tizen 6.5
 864  * @param[in] dp The data path handle
 865  * @param[in] port The port
 866  * @return 0 on success, otherwise a negative error value
 867  * @retval #VINE_ERROR_NONE     Successful
 868  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 869  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 870  * @see vine_dp_create()
 871  */
 872 int vine_dp_set_port(vine_dp_h dp, int port);
 873
 874 /**
 875  * @brief Gets the port.
 876  * @since_tizen 6.5
 877  * @param[in] dp The data path handle
 878  * @param[out] port The port
 879  * @return 0 on success, otherwise a negative error value
 880  * @retval #VINE_ERROR_NONE     Successful
 881  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 882  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 883  * @see vine_dp_create()
 884  */
 885 int vine_dp_get_port(vine_dp_h dp, int *port);
 886
 887 /**
 888  * @brief Sets the topic. Only for Publish-Subscribe type.
 889  * @remarks The length of @a topic should be less than 63 characters.
 890  * @since_tizen 6.5
 891  * @param[in] dp The data path handle
 892  * @param[in] topic The topic
 893  * @return 0 on success, otherwise a negative error value
 894  * @retval #VINE_ERROR_NONE     Successful
 895  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 896  * @retval #VINE_ERROR_INVALID_OPERATION        Invalid operation
 897  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 898  * @see vine_dp_create()
 899  */
 900 int vine_dp_set_topic(vine_dp_h dp, const char *topic);
 901
 902 /**
 903  * @brief Sets the maximum number of connections.
 904  * @remarks This doesn't affect the client dp or the opened dp.
 905  * @since_tizen 6.5
 906  * @param[in] dp The datapath handle
 907  * @param[in] max_conn The maximum number of connections
 908  * @return 0 on success, otherwise a negative error value
 909  * @retval #VINE_ERROR_NONE     Successful
 910  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 911  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 912  * @see vine_initialize()
 913  */
 914 int vine_dp_set_max_connections(vine_dp_h dp, int max_conn);
 915
 916 /**
 917  * @brief Sets the security information.
 918  * @remarks Releasing @a security after this function does not affect the operation of the datapath\
 919  *          because @a security is copied internally.
 920  * @since_tizen 6.5
 921  * @param[in] dp The data path handle
 922  * @param[in] security The security handle
 923  * @return 0 on success, otherwise a negative error value
 924  * @retval #VINE_ERROR_NONE     Successful
 925  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 926  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 927  * @see vine_dp_create()
 928  * @see vine_security_create()
 929  */
 930 int vine_dp_set_security(vine_dp_h dp, vine_security_h security);
 931
 932 /**
 933  * @brief Called whenever the peer is accepted.
 934  * @remarks @a dp must be released by vine_dp_destroy() if you don't use it anymore.
 935  * @since_tizen 6.5
 936  * @param[in] dp The data path handle
 937  * @param[in] accepted_dp The data path handle for accepted peer
 938  * @param[in] user_data The user data passed from the callback registration function
 939  * @see vine_dp_set_accepted_cb()
 940  */
 941 typedef void(*vine_dp_accepted_cb)(vine_dp_h dp, vine_dp_h accepted_dp, void *user_data);
 942
 943 /**
 944  * @brief Sets accepted callback called when peer is accepted.
 945  * @since_tizen 6.5
 946  * @param[in] dp The data path handle
 947  * @param[in] callback The accepted callback
 948  * @param[in] user_data The user data
 949  * @return 0 on success, otherwise a negative error value
 950  * @retval #VINE_ERROR_NONE     Successful
 951  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 952  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 953  * @see vine_dp_create()
 954  * @see vine_dp_unset_accepted_cb()
 955  */
 956 int vine_dp_set_accepted_cb(vine_dp_h dp, vine_dp_accepted_cb callback, void *user_data);
 957
 958 /**
 959  * @brief Unsets accepted callback.
 960  * @since_tizen 6.5
 961  * @param[in] dp The data path handle
 962  * @return 0 on success, otherwise a negative error value
 963  * @retval #VINE_ERROR_NONE     Successful
 964  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 965  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 966  * @see vine_dp_create()
 967  * @see vine_dp_set_accepted_cb()
 968  */
 969 int vine_dp_unset_accepted_cb(vine_dp_h dp);
 970
 971 /**
 972  * @brief Called when datapath is terminated by peer.
 973  * @since_tizen 6.5
 974  * @param[in] dp The terminated datapath
 975  * @param[in] user_data The user data passed from the callback registration function
 976  * @see vine_dp_set_terminated_cb()
 977  * @see vine_dp_unset_terminated_cb()
 978  */
 979 typedef void(*vine_dp_terminated_cb)(vine_dp_h dp, void *user_data);
 980
 981 /**
 982  * @brief Registers datapath terminated callback called when datapath is closed by peer.
 983  * @since_tizen 6.5
 984  * @param[in] dp The datapath handle
 985  * @param[in] callback The terminated callback
 986  * @param[in] user_data The user data
 987  * @return 0 on success, otherwise a negative error value
 988  * @retval #VINE_ERROR_NONE     Successful
 989  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
 990  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
 991  * @see vine_session_unset_data_path_terminated_cb()
 992  */
 993 int vine_dp_set_terminated_cb(vine_dp_h dp, vine_dp_terminated_cb callback, void *user_data);
 994
 995 /**
 996  * @brief Unregisters datapath terminated callback.
 997  * @since_tizen 6.5
 998  * @param[in] dp The datapath handle
 999  * @return 0 on success, otherwise a negative error value
1000  * @retval #VINE_ERROR_NONE     Successful
1001  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1002  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1003  * @see vine_session_set_data_path_terminated_cb()
1004  */
1005 int vine_dp_unset_terminated_cb(vine_dp_h dp);
1006
1007 /**
1008  * @brief Called when @a dp is opened.
1009  * @since_tizen 6.5
1010  * @param[in] dp The data path handle
1011  * @param[in] user_data The user data passed from vine_dp_open()
1012  * @see vine_dp_open()
1013  */
1014 typedef void (*vine_dp_opened_cb)(vine_dp_h dp, vine_error_e result, void *user_data);
1015
1016 /**
1017  * @brief Opens a datapath.
1018  * @remarks This works depending on the type of datapath differently.
1019  * If @a dp is a server, a listen port is opened.
1020  * If @a dp is a client, it tries to connect to a server.
1021  * If @a dp is for Publish-Subscribe, it joins to a service which has the same topic.
1022  * @since_tizen 6.5
1023  * @param[in] dp The data path handle
1024  * @param[in] callback The callback to be called
1025  * @param[in] user_data The user data passed to the callback function
1026  * @return 0 on success, otherwise a negative error value
1027  * @retval #VINE_ERROR_NONE     Successful
1028  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1029  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1030  * @see vine_dp_create()
1031  * @see vine_dp_close()
1032  */
1033 int vine_dp_open(vine_dp_h dp, vine_dp_opened_cb callback, void *user_data);
1034
1035 /**
1036  * @brief Closes the datapath.
1037  * @remarks The network connections with remote peers will be terminated.
1038  * @since_tizen 6.5
1039  * @param[in] dp The datapath handle
1040  * @return 0 on success, otherwise a negative error value
1041  * @retval #VINE_ERROR_NONE     Successful
1042  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1043  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1044  * @see vine_dp_open()
1045  */
1046 int vine_dp_close(vine_dp_h dp);
1047
1048 /**
1049  * @brief Sends a message through the datapath.
1050  * @since_tizen 6.5
1051  * @remarks @buf will be sent to a peer when writable state.
1052  * @param[in] dp The datapath handle
1053  * @param[in] buf The message to be written
1054  * @param[in] len The size in bytes to be written
1055  * @return 0 on success, otherwise a negative error value
1056  * @retval #VINE_ERROR_NONE     Successful
1057  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1058  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1059  * @see vine_dp_create()
1060  */
1061 int vine_dp_send(vine_dp_h dp, unsigned char *buf, size_t len);
1062
1063 /**
1064  * @brief Reads up to @buf_len bytes from a @datapath into @buf.
1065  * @since_tizen 6.5
1066  * @remarks This function can be called in vine_dp_received_cb() only.\
1067  *  If @buf_len is larger than @received_len of vine_dp_received_cb, \
1068  *  unexpected data can be read.
1069  * @param[in] dp The datapath handle
1070  * @param[in] buf The buffer to be filled out
1071  * @param[in] buf_len The buffer size
1072  * @param[out] read_len The size in bytes to be read
1073  * @return 0 on success, otherwise a negative error value
1074  * @retval #VINE_ERROR_NONE     Successful
1075  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1076  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1077  * @see vine_dp_create()
1078  * @see vine_dp_set_received_cb()
1079  */
1080 int vine_dp_recv(vine_dp_h dp,
1081                 unsigned char *buf, size_t buf_len, size_t *read_len);
1082
1083 /**
1084  * @brief Called when readable state.
1085  * @since_tizen 6.5
1086  * @remarks vine_dp_recv can be called in this callback
1087  * @param[in] dp  The datapath handle
1088  * @param[in] received_len The number of bytes transferred
1089  * @param[in] user_data The user data passed from the callback registration function
1090  * @see vine_dp_set_received_cb()
1091  * @see vine_dp_unset_received_cb()
1092  * @see vine_dp_read()
1093  */
1094 typedef void(*vine_dp_received_cb)(vine_dp_h dp, size_t received_len, void *user_data);
1095
1096 /**
1097  * @brief Registers the callback called when a message is received from a peer.
1098  * @since_tizen 6.5
1099  * @param[in] dp The datapath handle
1100  * @param[in] callback The callback function to be called
1101  * @param[in] user_data The user data passed to the callback function
1102  * @return 0 on success, otherwise a negative error value
1103  * @retval #VINE_ERROR_NONE     Successful
1104  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1105  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1106  * @see vine_dp_create()
1107  * @see vine_dp_unset_received_cb()
1108  */
1109 int vine_dp_set_received_cb(vine_dp_h dp, vine_dp_received_cb callback, void *user_data);
1110
1111 /**
1112  * @brief Unregisters the callback called when a message is received from a peer.
1113  * @since_tizen 6.5
1114  * @param[in] dp The datapath handle
1115  * @return 0 on success, otherwise a negative error value
1116  * @retval #VINE_ERROR_NONE     Successful
1117  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1118  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1119  * @see vine_initialize()
1120  * @see vine_dp_set_received_cb()
1121  */
1122 int vine_dp_unset_received_cb(vine_dp_h dp);
1123
1124 /**
1125  * @brief Creates a security configuration.
1126  * @since_tizen 6.5
1127  * @param[out] security The security handle
1128  * @return 0 on success, otherwise a negative error value
1129  * @retval #VINE_ERROR_NONE     Successful
1130  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1131  * @retval #VINE_ERROR_OUT_OF_MEMORY    Out of memory
1132  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1133  * @see vine_security_destroy()
1134  */
1135 int vine_security_create(vine_security_h *security);
1136
1137 /**
1138  * @brief Destroys a security configuration.
1139  * @since_tizen 6.5
1140  * @param[in] security The security handle
1141  * @return 0 on success, otherwise a negative error value
1142  * @retval #VINE_ERROR_NONE     Successful
1143  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1144  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1145  * @see vine_security_create()
1146  */
1147 int vine_security_destroy(vine_security_h security);
1148
1149 /**
1150  * @brief Sets a security type.
1151  * @since_tizen 6.5
1152  * @param[in] security The security handle
1153  * @param[in] type      The security type
1154  * @return 0 on success, otherwise a negative error value
1155  * @retval #VINE_ERROR_NONE     Successful
1156  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1157  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1158  * @see vine_security_get_type()
1159  */
1160 int vine_security_set_type(vine_security_h security, vine_security_type_e type);
1161
1162 /**
1163  * @brief Gets a security type.
1164  * @since_tizen 6.5
1165  * @param[in] security The security handle
1166  * @param[out] type The security type
1167  * @return 0 on success, otherwise a negative error value
1168  * @retval #VINE_ERROR_NONE     Successful
1169  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1170  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1171  * @see vine_security_set_type()
1172  */
1173 int vine_security_get_type(vine_security_h security, vine_security_type_e *type);
1174
1175 /**
1176  * @brief Sets TLS version range.
1177  * @remarks SSLv2 and SSLv3 are not supported because both versions were proven to be insecure.
1178  * @since_tizen 6.5
1179  * @param[in] security The security handle
1180  * @param[in] version The TLS version
1181  * @return 0 on success, otherwise a negative error value
1182  * @retval #VINE_ERROR_NONE     Successful
1183  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1184  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1185  * @see vine_security_get_tls_version()
1186  * @see vine_security_set_type()
1187  */
1188 int vine_security_set_tls_version(vine_security_h security, vine_security_tls_version_e version);
1189
1190 /**
1191  * @brief Gets TLS version range.
1192  * @since_tizen 6.5
1193  * @param[in] security The security handle
1194  * @param[in] version The TLS version
1195  * @return 0 on success, otherwise a negative error value
1196  * @retval #VINE_ERROR_NONE     Successful
1197  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1198  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1199  * @see vine_security_set_tls_version()
1200  * @see vine_security_set_type()
1201  */
1202 int vine_security_get_tls_version(vine_security_h security, vine_security_tls_version_e *version);
1203
1204 /**
1205  * @brief Sets combination of verification flags.
1206  * @since_tizen 6.5
1207  * @param[in] security The security handle
1208  * @param[in] flags The bitwise set of one or more of @a vine_security_verification_flag_e
1209  * @return 0 on success, otherwise a negative error value
1210  * @retval #VINE_ERROR_NONE     Successful
1211  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1212  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1213  * @see vine_security_get_verification_flags()
1214  * @see vine_security_set_type()
1215  */
1216 int vine_security_set_verification_flags(vine_security_h security, int flags);
1217
1218 /**
1219  * @brief Gets combination of verification flags.
1220  * @since_tizen 6.5
1221  * @param[in] security The security handle
1222  * @param[out] flags The bitwise set of one or more of @a vine_security_verification_flag_e
1223  * @return 0 on success, otherwise a negative error value
1224  * @retval #VINE_ERROR_NONE     Successful
1225  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1226  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1227  * @see vine_security_set_verification_flags()
1228  */
1229 int vine_security_get_verification_flags(vine_security_h security, int *flags);
1230
1231 /**
1232  * @brief Sets CA(Certificate Authority) certificates path.
1233  * @remarks The certificates in @ca_path are used when verifying the peer.
1234  * @since_tizen 6.5
1235  * @param[in] security The security handle
1236  * @param[in] ca_path The directory holding CA certificates
1237  * @return 0 on success, otherwise a negative error value
1238  * @retval #VINE_ERROR_NONE     Successful
1239  * @retval #VINE_ERROR_INVALID_PARAMTER Invalid parameter
1240  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1241  * @see vine_security_get_ca_path()
1242  */
1243 int vine_security_set_ca_path(vine_security_h security, const char *ca_path);
1244
1245 /**
1246  * @brief Gets CA(Certificate Authority) certificates path.
1247  * @remarks @a ca_path must be released using free().
1248  * @since_tizen 6.5
1249  * @param[in] security The security handle
1250  * @param[out] ca_path The directory holding CA certificates
1251  * @return 0 on success, otherwise a negative error value
1252  * @retval #VINE_ERROR_NONE     Successful
1253  * @retval #VINE_ERROR_INVALID_PARAMTER Invalid parameter
1254  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1255  * @see vine_security_set_ca_path()
1256  */
1257 int vine_security_get_ca_path(vine_security_h security, char **ca_path);
1258
1259 /**
1260  * @brief Sets certificate path.
1261  * @remarks The certificate is transfered to peer during TLS/SSL handshaking.
1262  * @since_tizen 6.5
1263  * @param[in] security The security handle.
1264  * @param[in] cert_path The certificate path.
1265  * @return 0 on success, otherwise a negative error value
1266  * @retval #VINE_ERROR_NONE     Successful
1267  * @retval #VINE_ERROR_INVALID_PARAMTER Invalid parameter
1268  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1269  * @see vine_security_set_type()
1270  * @see vine_security_set_private_key()
1271  */
1272 int vine_security_set_cert_path(vine_security_h security, const char *cert_path);
1273
1274 /**
1275  * @brief Gets certificate path.
1276  * @remarks @a cert_path must be released using free().
1277  * @since_tizen 6.5
1278  * @param[in] security The security handle.
1279  * @param[out] cert_path The certificate path.
1280  * @return 0 on success, otherwise a negative error value
1281  * @retval #VINE_ERROR_NONE     Successful
1282  * @retval #VINE_ERROR_INVALID_PARAMTER Invalid parameter
1283  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1284  * @see vine_security_set_cert_path()
1285  */
1286 int vine_security_get_cert_path(vine_security_h security, char **cert_path);
1287
1288 /**
1289  * @brief Sets key path for the certificate.
1290  * @since_tizen 6.5
1291  * @param[in] security The security handle.
1292  * @param[in] key_path The key path.
1293  * @return 0 on success, otherwise a negative error value
1294  * @retval #VINE_ERROR_NONE     Successful
1295  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1296  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1297  * @see vine_security_set_type()
1298  * @see vine_security_set_cert_path()
1299  */
1300 int vine_security_set_private_key(vine_security_h security, const char *key_path);
1301
1302 /**
1303  * @brief Gets key path for the certificate.
1304  * @remarks @a key_path must be released using free().
1305  * @since_tizen 6.5
1306  * @param[in] security The security handle.
1307  * @param[out] key_path The key path.
1308  * @return 0 on success, otherwise a negative error value
1309  * @retval #VINE_ERROR_NONE     Successful
1310  * @retval #VINE_ERROR_INVALID_PARAMETER        Invalid parameter
1311  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1312  * @see vine_security_set_private_key()
1313  */
1314 int vine_security_get_private_key(vine_security_h security, char **key_path);
1315
1316 /**
1317  * @brief Sets preshared key to verify peer.
1318  * @remarks The @psk is exchanged over a websocket connection.
1319  * @since_tizen 6.5
1320  * @param[in] security The security handle.
1321  * @param[in] psk The preshared key
1322  * @return 0 on success, otherwise a negative error value
1323  * @retval #VINE_ERROR_NONE     Successful
1324  * @retval #VINE_ERROR_INVALID_PARAMTER Invalid parameter
1325  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1326  * @see vine_security_get_psk()
1327  */
1328 int vine_security_set_psk(vine_security_h security, const char *psk);
1329
1330 /**
1331  * @brief Gets preshared key to verify peer.
1332  * @remarks @a psk must be released using free().
1333  * @since_tizen 6.5
1334  * @param[in] security The security handle.
1335  * @param[out] psk The preshared key
1336  * @return 0 on success, otherwise a negative error value
1337  * @retval #VINE_ERROR_NONE     Successful
1338  * @retval #VINE_ERROR_INVALID_PARAMTER Invalid parameter
1339  * @retval #VINE_ERROR_NOT_SUPPORTED Not supported
1340  * @see vine_security_set_psk()
1341  */
1342 int vine_security_get_psk(vine_security_h security, char **psk);
1343
1344 /**
1345  * @}
1346  */
1347
1348 #ifdef __cplusplus
1349 }
1350 #endif
1351
1352 #endif /* __VINE_H__ */
1353