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