include/sock.h: add comments for public APIs (39cd6f85) · Commits · Public Repositories / spdk

include/spdk/sock.h

+166 −0

Original line number	Diff line number	Diff line
		@@ -47,29 +47,195 @@ extern "C" {
		struct spdk_sock;
		struct spdk_sock_group;

		/**
		* Get client and server addresses of the given socket.
		*
		* \param sock Socket to get address.
		* \param saddr A pointer to the buffer to hold the address of server.
		* \param slen Length of the buffer 'saddr'.
		* \param caddr A pointer to the buffer to hold the address of client.
		* \param slen Length of the buffer 'caddr'.
		*
		* \return 0 on success, -1 on failure.
		*/
		int spdk_sock_getaddr(struct spdk_sock sock, char saddr, int slen, char *caddr, int clen);

		/**
		* Create a socket, connect the socket to the specified address and port (of the
		* server), and then return the socket. This function is used by client.
		*
		* \param ip IP address of the server.
		* \param port Port number of the server.
		*
		* \return a pointer to the connected socket on success, or NULL on failure.
		*/
		struct spdk_sock spdk_sock_connect(const char ip, int port);

		/**
		* Create a socket, bind the socket to the specified address and port and listen
		* on the socket, and then return the socket. This function is used by server.
		*
		* \param ip IP address to listen on.
		* \param port Port number.
		*
		* \return a pointer to the listened socket on success, or NULL on failure.
		*/
		struct spdk_sock spdk_sock_listen(const char ip, int port);

		/**
		* Accept a new connection from a client on the specified socket and return a
		* socket structure which holds the connection.
		*
		* \param sock Listening socket.
		*
		* \return a pointer to the accepted socket on success, or NULL on failure.
		*/
		struct spdk_sock spdk_sock_accept(struct spdk_sock sock);

		/**
		* Close a socket.
		*
		* \param sock Socket to close.
		*
		* \return 0 on success, -1 on failure.
		*/
		int spdk_sock_close(struct spdk_sock **sock);

		/**
		* Receive a message from the given socket.
		*
		* \param sock Socket to receive message.
		* \param buf Pointer to a buffer to hold the data.
		* \param len Length of the buffer.
		*
		* \return the length of the received message on success, -1 on failure.
		*/
		ssize_t spdk_sock_recv(struct spdk_sock sock, void buf, size_t len);

		/**
		* Write message to the given socket from the I/O vector array.
		*
		* \param sock Socket to write to.
		* \param iov I/O vector.
		* \param iovcnt Number of I/O vectors in the array.
		*
		* \return the length of written message on success, -1 on failure.
		*/
		ssize_t spdk_sock_writev(struct spdk_sock sock, struct iovec iov, int iovcnt);

		/**
		* Set the value used to specify the low water mark (in bytes) for this socket.
		*
		* \param sock Socket to set for.
		* \param nbytes Value for recvlowat.
		*
		* \return 0 on success, -1 on failure.
		*/
		int spdk_sock_set_recvlowat(struct spdk_sock *sock, int nbytes);

		/**
		* Set receive buffer size for the given socket.
		*
		* \param sock Socket to set buffer size for.
		* \param sz Buffer size in bytes.
		*
		* \return 0 on success, -1 on failure.
		*/
		int spdk_sock_set_recvbuf(struct spdk_sock *sock, int sz);

		/**
		* Set send buffer size for the given socket.
		*
		* \param sock Socket to set buffer size for.
		* \param sz Buffer size in bytes.
		*
		* \return 0 on success, -1 on failure.
		*/
		int spdk_sock_set_sendbuf(struct spdk_sock *sock, int sz);

		/**
		* Check whether the address of socket is ipv6.
		*
		* \param sock Socket to check.
		*
		* \return true if the address of socket is ipv6, or false otherwise.
		*/
		bool spdk_sock_is_ipv6(struct spdk_sock *sock);

		/**
		* Check whether the address of socket is ipv4.
		*
		* \param sock Socket to check.
		*
		* \return true if the address of socket is ipv4, or false otherwise.
		*/
		bool spdk_sock_is_ipv4(struct spdk_sock *sock);

		/**
		* Callback function for spdk_sock_group_add_sock().
		*
		* \param arg Argument for the callback function.
		* \param group Socket group.
		* \param sock Socket.
		*/
		typedef void (spdk_sock_cb)(void arg, struct spdk_sock_group group, struct spdk_sock sock);

		/**
		* Create a new socket group.
		*
		* \return a pointer to the created group on success, or NULL on failure.
		*/
		struct spdk_sock_group *spdk_sock_group_create(void);

		/**
		* Add a socket to the group.
		*
		* \param group Socket group.
		* \param sock Socket to add.
		* \param cb_fn Called when the operation completes.
		* \param cb_arg Argument passed to the callback function.
		*
		* \return 0 on success, -1 on failure.
		*/
		int spdk_sock_group_add_sock(struct spdk_sock_group group, struct spdk_sock sock,
		spdk_sock_cb cb_fn, void *cb_arg);

		/**
		* Remove a socket from the group.
		*
		* \param group Socket group.
		* \param sock Socket to remove.
		*
		* \return 0 on success, -1 on failure.
		*/
		int spdk_sock_group_remove_sock(struct spdk_sock_group group, struct spdk_sock sock);

		/**
		* Poll incoming events for each registered socket.
		*
		* \param group Group to poll.
		*
		* \return 0 on success, -1 on failure.
		*/
		int spdk_sock_group_poll(struct spdk_sock_group *group);

		/**
		* Poll incoming events up to max_events for each registered socket.
		*
		* \param group Group to poll.
		* \param max_events Number of maximum events to poll for each socket.
		*
		* \return the number of events on success, -1 on failure.
		*/
		int spdk_sock_group_poll_count(struct spdk_sock_group *group, int max_events);

		/**
		* Close all registered sockets of the group and then remove the group.
		*
		* \param group Group to close.
		*
		* \return 0 on success, -1 on failure.
		*/
		int spdk_sock_group_close(struct spdk_sock_group **group);

		#ifdef __cplusplus