Changes in uspace/lib/c/generic/inet/udp.c [1f2b07a:f9b2cb4c] in mainline

File:

• uspace/lib/c/generic/inet/udp.c (modified) (20 diffs)

uspace/lib/c/generic/inet/udp.c

@@ -43 +43 @@
 static void udp_cb_conn(ipc_callid_t, ipc_call_t *, void *);
 
+/** Create callback connection from UDP service.
+ *
+ * @param udp UDP service
+ * @return EOK on success or negative error code
+ */
 static int udp_callback_create(udp_t *udp)
 {
@@ -48 +53 @@
 
         aid_t req = async_send_0(exch, UDP_CALLBACK_CREATE, NULL);
-        int rc = async_connect_to_me(exch, 0, 0, 0, udp_cb_conn, udp);
+        
+        port_id_t port;
+        int rc = async_create_callback_port(exch, INTERFACE_UDP_CB, 0, 0,
+            udp_cb_conn, udp, &port);
+        
         async_exchange_end(exch);
 
@@ -60 +69 @@
 }
 
+/** Create UDP client instance.
+ *
+ * @param  rudp Place to store pointer to new UDP client
+ * @return EOK on success, ENOMEM if out of memory, EIO if service
+ *         cannot be contacted
+ */
 int udp_create(udp_t **rudp)
 {
@@ -83 +98 @@
         }
 
-        udp->sess = loc_service_connect(EXCHANGE_SERIALIZE, udp_svcid,
+        udp->sess = loc_service_connect(udp_svcid, INTERFACE_UDP,
             IPC_FLAG_BLOCKING);
         if (udp->sess == NULL) {
@@ -103 +118 @@
 }
 
+/** Destroy UDP client instance.
+ *
+ * @param udp UDP client
+ */
 void udp_destroy(udp_t *udp)
 {
@@ -118 +137 @@
 }
 
-int udp_assoc_create(udp_t *udp, inet_ep2_t *ep2, udp_cb_t *cb, void *arg,
+/** Create new UDP association.
+ *
+ * Create a UDP association that allows sending and receiving messages.
+ *
+ * @a epp may specify remote address and port, in which case only messages
+ * from that remote endpoint will be received. Also, that remote endpoint
+ * is used as default when @c NULL is passed as destination to
+ * udp_assoc_send_msg.
+ *
+ * @a epp may specify a local link or address. If it does not, the association
+ * will listen on all local links/addresses. If @a epp does not specify
+ * a local port number, a free dynamic port number will be allocated.
+ *
+ * The caller is informed about incoming data by invoking @a cb->recv_msg
+ *
+ * @param udp    UDP client
+ * @param epp    Internet endpoint pair
+ * @param cb     Callbacks
+ * @param arg    Argument to callbacks
+ * @param rassoc Place to store pointer to new association
+ *
+ * @return EOK on success or negative error code.
+ */
+int udp_assoc_create(udp_t *udp, inet_ep2_t *epp, udp_cb_t *cb, void *arg,
     udp_assoc_t **rassoc)
 {
@@ -131 +173 @@
         exch = async_exchange_begin(udp->sess);
         aid_t req = async_send_0(exch, UDP_ASSOC_CREATE, &answer);
-        sysarg_t rc = async_data_write_start(exch, (void *)ep2,
+        sysarg_t rc = async_data_write_start(exch, (void *)epp,
             sizeof(inet_ep2_t));
         async_exchange_end(exch);
@@ -161 +203 @@
 }
 
+/** Destroy UDP association.
+ *
+ * Destroy UDP association. The caller should destroy all associations
+ * he created before destroying the UDP client and before terminating.
+ *
+ * @param assoc UDP association
+ */
 void udp_assoc_destroy(udp_assoc_t *assoc)
 {
@@ -178 +227 @@
 }
 
+/** Send message via UDP association.
+ *
+ * @param assoc Association
+ * @param dest  Destination endpoint or @c NULL to use association's remote ep.
+ * @param data  Message data
+ * @param bytes Message size in bytes
+ *
+ * @return EOK on success or negative error code
+ */
 int udp_assoc_send_msg(udp_assoc_t *assoc, inet_ep_t *dest, void *data,
     size_t bytes)
@@ -211 +269 @@
 }
 
+/** Get the user/callback argument for an association.
+ *
+ * @param assoc UDP association
+ * @return User argument associated with association
+ */
 void *udp_assoc_userptr(udp_assoc_t *assoc)
 {
@@ -216 +279 @@
 }
 
+/** Get size of received message in bytes.
+ *
+ * Assuming jumbo messages can be received, the caller first needs to determine
+ * the size of the received message by calling this function, then they can
+ * read the message piece-wise using udp_rmsg_read().
+ *
+ * @param rmsg Received message
+ * @return Size of received message in bytes
+ */
 size_t udp_rmsg_size(udp_rmsg_t *rmsg)
 {
@@ -221 +293 @@
 }
 
+/** Read part of received message.
+ *
+ * @param rmsg  Received message
+ * @param off   Start offset
+ * @param buf   Buffer for storing data
+ * @param bsize Buffer size
+ *
+ * @return EOK on success or negative error code.
+ */
 int udp_rmsg_read(udp_rmsg_t *rmsg, size_t off, void *buf, size_t bsize)
 {
@@ -245 +326 @@
 }
 
+/** Get remote endpoint of received message.
+ *
+ * Place the remote endpoint (the one from which the message was supposedly
+ * sent) to @a ep.
+ *
+ * @param rmsg Received message
+ * @param ep   Place to store remote endpoint
+ */
 void udp_rmsg_remote_ep(udp_rmsg_t *rmsg, inet_ep_t *ep)
 {
@@ -250 +339 @@
 }
 
+/** Get type of received ICMP error message.
+ *
+ * @param rerr Received error message
+ * @return Error message type
+ */
 uint8_t udp_rerr_type(udp_rerr_t *rerr)
 {
@@ -255 +349 @@
 }
 
+/** Get code of received ICMP error message.
+ *
+ * @param rerr Received error message
+ * @return Error message code
+ */
 uint8_t udp_rerr_code(udp_rerr_t *rerr)
 {
@@ -260 +359 @@
 }
 
+/** Get information about the next received message from UDP service.
+ *
+ * @param udp  UDP client
+ * @param rmsg Place to store message information
+ *
+ * @return EOK on success or negative error code
+ */
 static int udp_rmsg_info(udp_t *udp, udp_rmsg_t *rmsg)
 {
@@ -288 +394 @@
 }
 
+/** Discard next received message in UDP service.
+ *
+ * @param udp UDP client
+ * @return EOK on success or negative error code
+ */
 static int udp_rmsg_discard(udp_t *udp)
 {
@@ -299 +410 @@
 }
 
+/** Get association based on its ID.
+ *
+ * @param udp    UDP client
+ * @param id     Association ID
+ * @param rassoc Place to store pointer to association
+ *
+ * @return EOK on success, EINVAL if no association with the given ID exists
+ */
 static int udp_assoc_get(udp_t *udp, sysarg_t id, udp_assoc_t **rassoc)
 {
@@ -311 +430 @@
 }
 
+/** Handle 'data' event, i.e. some message(s) arrived.
+ *
+ * For each received message, get information about it, call @c recv_msg
+ * callback and discard it.
+ *
+ * @param udp UDP client
+ * @param iid IPC message ID
+ * @param icall IPC message
+ */
 static void udp_ev_data(udp_t *udp, ipc_callid_t iid, ipc_call_t *icall)
 {
@@ -340 +468 @@
 }
 
+/** UDP service callback connection.
+ *
+ * @param iid Connect message ID
+ * @param icall Connect message
+ * @param arg Argument, UDP client
+ */
 static void udp_cb_conn(ipc_callid_t iid, ipc_call_t *icall, void *arg)
 {