2 * Copyright (c) 2021 Samsung Electronics Co., Ltd. All rights reserved.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
38 * @addtogroup VINE_MODULE
43 #define VINE_ERROR -0x03050000
47 * @brief Enumeration for Vine error code.
56 * Operation not permitted(1)
58 VINE_ERROR_NOT_PERMITTED = -EPERM,
62 VINE_ERROR_OUT_OF_MEMORY = -ENOMEM,
64 * Permission denied(13)
66 VINE_ERROR_PERMISSION_DENIED = -EACCES,
68 * Invalid function parameter(22)
70 VINE_ERROR_INVALID_PARAMETER = -EINVAL,
72 * Invalid operation(38)
74 VINE_ERROR_INVALID_OPERATION = -ENOSYS,
76 * Connection timed out(110)
78 VINE_ERROR_CONNECTION_TIME_OUT = -ETIMEDOUT,
80 * Now in progress(115)
82 VINE_ERROR_NOW_IN_PROGRESS = -EINPROGRESS,
86 VINE_ERROR_NOT_SUPPORTED,
90 VINE_ERROR_NOT_INITIALIZED = VINE_ERROR|0x01,
94 VINE_ERROR_ALREADY_INITIALIZED = VINE_ERROR|0x02,
98 VINE_ERROR_ALREADY_ENABLED = VINE_ERROR|0x03,
102 VINE_ERROR_OPERATION_FAILED = VINE_ERROR|0x04,
104 * Service name conflicted
106 VINE_ERROR_NAME_CONFLICT = VINE_ERROR|0x05,
110 VINE_ERROR_NO_READ_DATA = VINE_ERROR|0x06,
114 //VINE_ERROR_REJECTED_BY_PEER = VINE_ERROR|0x05,
116 * Wi-Fi Interface is down
118 //VINE_ERROR_INTERFACE_DOWN = -ENETDOWN,
123 * @brief Enumeration for data path type
130 VINE_DP_TYPE_SERVER = 0,
136 * Publish-Subscirbe type
146 * @brief Enumeration for security configuration
153 VINE_SECURITY_TYPE_NONE = 0,
155 * Uses TLS/SSL for encrypted communication
157 VINE_SECURITY_TYPE_TLS = 1,
159 * Attempts PSK authentication over TLS connection
161 VINE_SECURITY_TYPE_PSK_OVER_TLS = 2,
162 } vine_security_type_e;
165 * @brief Enumeration for TLS version
170 * Default TLS version
172 VINE_SECURITY_TLS_VERSION_DEFAULT = 0,
176 VINE_SECURITY_TLS_VERSION_1_0 = 100,
180 VINE_SECURITY_TLS_VERSION_1_1 = 101,
184 VINE_SECURITY_TLS_VERSION_1_2 = 102,
188 VINE_SECURITY_TLS_VERSION_1_3 = 103,
189 } vine_security_tls_version_e;
192 * @brief Enumeration for certificate verification flag
199 VINE_SECURITY_VERIFICATION_FLAG_DEFAULT = 0,
201 * Allows self-signed ceritifcate
203 VINE_SECURITY_VERIFICATION_FLAG_ALLOW_SELF_SIGNED = (1 << 0),
205 * Skips host name(CN) check
207 VINE_SECURITY_VERIFICATION_FLAG_SKIP_HOST_NAME_CHECK = (1 << 1),
208 } vine_security_verification_flag_e;
212 * The discovered service is unavailable
214 VINE_SERVICE_UNAVAILABLE = 0,
216 * The discovered service is available
218 VINE_SERVICE_AVAILABLE,
219 } vine_service_state_e;
222 * @brief Enumeration for capability type.
227 * The possible discovery methods.
229 VINE_CAPA_DISCOVERY_METHODS = 0,
231 * The max number of connections.
233 VINE_CAPA_MAX_CONNECTIONS,
234 } vine_capability_type_e;
237 * @brief Publish Session
240 typedef void *vine_session_h;
246 typedef void *vine_service_h;
252 typedef void *vine_dp_h;
255 * @brief Security configuration
258 typedef void *vine_security_h;
261 * @brief Enumeration for service discovery method
265 VINE_DISCOVERY_METHOD_DNS_SD = 0,
266 } vine_discovery_method_e;
269 * @brief Enumeration for address family
275 * IPv6 has a higher priority than IPv4.
276 * For example, IPv6 is used in the dual stack.
278 VINE_ADDRESS_FAMILY_DEFAULT = 0,
282 VINE_ADDRESS_FAMILY_IPV4,
286 VINE_ADDRESS_FAMILY_IPV6,
287 } vine_address_family_e;
290 * @brief Initializes Vine.
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()
299 int vine_initialize();
302 * @brief Deinitializes Vine.
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()
310 int vine_deinitialize();
313 * @brief Gets the capabilities corresponding to @a type.
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()
323 int vine_get_capabilities(vine_capability_type_e type, int *capabilities);
326 * @brief Gets event file discriptor for monitoring Vine events.
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
334 int vine_session_get_event_fd(vine_session_h session, int *fd);
337 * @brief Process occurred event.
338 * @remarks This function should be called in event thread or context.
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
348 int vine_session_process_event(vine_session_h session);
351 * @brief Creates a session.
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()
361 int vine_session_create(vine_session_h *session);
364 * @brief Destroys a publish session.
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()
373 int vine_session_destroy(vine_session_h session);
376 * @brief Called when service is registered.
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()
385 typedef void(*vine_session_registered_cb)(vine_session_h session,
386 const char *service_name, vine_error_e error, void *user_data);
389 * @brief Sets registered callback called when service is registered.
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()
400 int vine_session_set_registered_cb(vine_session_h session,
401 vine_session_registered_cb callback, void *user_data);
404 * @brief Unsets registered callback.
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()
413 int vine_session_unset_registered_cb(vine_session_h session);
416 * @brief Called when service is discovered.
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()
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);
429 * @brief Registers discovered callback called when service is discovered.
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()
440 int vine_session_set_discovered_cb(vine_session_h session,
441 vine_session_discovered_cb callback, void *user_data);
444 * @brief Unregisters discovered callback.
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()
453 int vine_session_unset_discovered_cb(vine_session_h session);
456 * @brief Set the service discovery method
457 * @remarks Default service discovery method is DNS-SD
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()
467 int vine_session_set_discovery_method(vine_session_h session, vine_discovery_method_e method);
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.
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()
486 int vine_session_register(vine_session_h session,
487 vine_service_h service, const char *iface_name);
490 * @brief Unregisters a service.
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()
501 int vine_session_unregister(vine_session_h session);
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.
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()
520 int vine_session_start_discovery(vine_session_h session,
521 const char *service_type, const char *iface_name);
524 * @brief Stops a service discovery
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()
535 int vine_session_stop_discovery(vine_session_h session);
538 * @brief Called when an IP address is resolved.
539 * @remarks @a ip must be released using free().
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()
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 */
552 * @brief Resolves IP addresses for @a service.
553 * @remarks This API works only for @a service discovered by vine_session_discovered_cb callback
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
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);
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
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
578 int vine_session_unset_ip_resolved_cb(vine_session_h session,
579 vine_service_h service);
582 * @brief Creates a service.
583 * @remarks @a service should be released using vine_service_destroy().
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()
592 int vine_service_create(vine_service_h *service);
595 * @brief Destroys a service.
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()
604 int vine_service_destroy(vine_service_h service);
607 * @brief Clones a service handle.
608 * @remarks @a cloned should be released using vine_service_destroy().
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()
618 int vine_service_clone(vine_service_h origin, vine_service_h *cloned);
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.
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()
636 int vine_service_set_type(vine_service_h service, const char *service_type);
639 * @brief Gets the service type for the service.
640 * @remarks @a service_type must be released using free().
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()
651 int vine_service_get_type(vine_service_h service, char **service_type);
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.
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()
669 int vine_service_set_name(vine_service_h service, const char *service_name);
672 * @brief Gets the name for the service.
673 * @remarks @a service_name must be released using free().
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()
684 int vine_service_get_name(vine_service_h service, char **service_name);
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.
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()
709 int vine_service_add_attribute(vine_service_h service,
710 const char *key, const char *value);
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.
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()
725 int vine_service_remove_attribute(vine_service_h service, const char *key);
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.
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()
741 typedef bool(*vine_service_attribute_cb)(
742 const char *key, const char *value, void *user_data);
745 * @brief Gets the list of attributes. Each attribute is represented as a <key, value> pair.
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
757 int vine_service_foreach_attribute(vine_service_h service,
758 vine_service_attribute_cb callback, void *user_data);
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.
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()
773 int vine_service_set_port(vine_service_h service, int port);
776 * @brief Gets the port number.
777 * @remarks @a port will be 0 if it isn't set up.
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()
787 int vine_service_get_port(vine_service_h service, int *port);
790 * @brief Creates the data path handle.
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()
802 int vine_dp_create(vine_session_h session, vine_dp_type_e type, vine_dp_h *dp);
805 * @brief Destroys the data path handle.
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()
814 int vine_dp_destroy(vine_dp_h dp);
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.
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()
828 int vine_dp_set_iface_name(vine_dp_h dp, const char *iface_or_ip);
831 * @brief Sets the address family.
832 * @remarks This is ignored when dp type is VINE_DP_TYPE_CLIENT.
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()
842 int vine_dp_set_address_family(vine_dp_h dp, vine_address_family_e addr_family);
845 * @brief Sets the remote IP address.
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()
856 int vine_dp_set_remote_ip(vine_dp_h dp, vine_address_family_e addr_family, const char *ip);
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.
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()
872 int vine_dp_set_port(vine_dp_h dp, int port);
875 * @brief Gets the port.
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()
885 int vine_dp_get_port(vine_dp_h dp, int *port);
888 * @brief Sets the topic. Only for Publish-Subscribe type.
889 * @remarks The length of @a topic should be less than 63 characters.
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()
900 int vine_dp_set_topic(vine_dp_h dp, const char *topic);
903 * @brief Sets the maximum number of connections.
904 * @remarks This doesn't affect the client dp or the opened dp.
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()
914 int vine_dp_set_max_connections(vine_dp_h dp, int max_conn);
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.
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()
930 int vine_dp_set_security(vine_dp_h dp, vine_security_h security);
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.
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()
941 typedef void(*vine_dp_accepted_cb)(vine_dp_h dp, vine_dp_h accepted_dp, void *user_data);
944 * @brief Sets accepted callback called when peer is accepted.
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()
956 int vine_dp_set_accepted_cb(vine_dp_h dp, vine_dp_accepted_cb callback, void *user_data);
959 * @brief Unsets accepted callback.
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()
969 int vine_dp_unset_accepted_cb(vine_dp_h dp);
972 * @brief Called when datapath is terminated by peer.
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()
979 typedef void(*vine_dp_terminated_cb)(vine_dp_h dp, void *user_data);
982 * @brief Registers datapath terminated callback called when datapath is closed by peer.
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()
993 int vine_dp_set_terminated_cb(vine_dp_h dp, vine_dp_terminated_cb callback, void *user_data);
996 * @brief Unregisters datapath terminated callback.
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()
1005 int vine_dp_unset_terminated_cb(vine_dp_h dp);
1008 * @brief Called when @a dp is opened.
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()
1014 typedef void (*vine_dp_opened_cb)(vine_dp_h dp, vine_error_e result, void *user_data);
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.
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()
1033 int vine_dp_open(vine_dp_h dp, vine_dp_opened_cb callback, void *user_data);
1036 * @brief Closes the datapath.
1037 * @remarks The network connections with remote peers will be terminated.
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()
1046 int vine_dp_close(vine_dp_h dp);
1049 * @brief Sends a message through the datapath.
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()
1061 int vine_dp_send(vine_dp_h dp, unsigned char *buf, size_t len);
1064 * @brief Reads up to @buf_len bytes from a @datapath into @buf.
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()
1080 int vine_dp_recv(vine_dp_h dp,
1081 unsigned char *buf, size_t buf_len, size_t *read_len);
1084 * @brief Called when readable state.
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()
1094 typedef void(*vine_dp_received_cb)(vine_dp_h dp, size_t received_len, void *user_data);
1097 * @brief Registers the callback called when a message is received from a peer.
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()
1109 int vine_dp_set_received_cb(vine_dp_h dp, vine_dp_received_cb callback, void *user_data);
1112 * @brief Unregisters the callback called when a message is received from a peer.
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()
1122 int vine_dp_unset_received_cb(vine_dp_h dp);
1125 * @brief Creates a security configuration.
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()
1135 int vine_security_create(vine_security_h *security);
1138 * @brief Destroys a security configuration.
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()
1147 int vine_security_destroy(vine_security_h security);
1150 * @brief Sets a security type.
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()
1160 int vine_security_set_type(vine_security_h security, vine_security_type_e type);
1163 * @brief Gets a security type.
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()
1173 int vine_security_get_type(vine_security_h security, vine_security_type_e *type);
1176 * @brief Sets TLS version range.
1177 * @remarks SSLv2 and SSLv3 are not supported because both versions were proven to be insecure.
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()
1188 int vine_security_set_tls_version(vine_security_h security, vine_security_tls_version_e version);
1191 * @brief Gets TLS version range.
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()
1202 int vine_security_get_tls_version(vine_security_h security, vine_security_tls_version_e *version);
1205 * @brief Sets combination of verification flags.
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()
1216 int vine_security_set_verification_flags(vine_security_h security, int flags);
1219 * @brief Gets combination of verification flags.
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()
1229 int vine_security_get_verification_flags(vine_security_h security, int *flags);
1232 * @brief Sets CA(Certificate Authority) certificates path.
1233 * @remarks The certificates in @ca_path are used when verifying the peer.
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()
1243 int vine_security_set_ca_path(vine_security_h security, const char *ca_path);
1246 * @brief Gets CA(Certificate Authority) certificates path.
1247 * @remarks @a ca_path must be released using free().
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()
1257 int vine_security_get_ca_path(vine_security_h security, char **ca_path);
1260 * @brief Sets certificate path.
1261 * @remarks The certificate is transfered to peer during TLS/SSL handshaking.
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()
1272 int vine_security_set_cert_path(vine_security_h security, const char *cert_path);
1275 * @brief Gets certificate path.
1276 * @remarks @a cert_path must be released using free().
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()
1286 int vine_security_get_cert_path(vine_security_h security, char **cert_path);
1289 * @brief Sets key path for the certificate.
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()
1300 int vine_security_set_private_key(vine_security_h security, const char *key_path);
1303 * @brief Gets key path for the certificate.
1304 * @remarks @a key_path must be released using free().
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()
1314 int vine_security_get_private_key(vine_security_h security, char **key_path);
1317 * @brief Sets preshared key to verify peer.
1318 * @remarks The @psk is exchanged over a websocket connection.
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()
1328 int vine_security_set_psk(vine_security_h security, const char *psk);
1331 * @brief Gets preshared key to verify peer.
1332 * @remarks @a psk must be released using free().
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()
1342 int vine_security_get_psk(vine_security_h security, char **psk);
1352 #endif /* __VINE_H__ */