Changeset b10460a in mainline for uspace/lib/c


Ignore:
Timestamp:
2015-08-07T21:39:00Z (10 years ago)
Author:
Jiri Svoboda <jiri@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
b688fd8
Parents:
6accc5cf
Message:

Add missing docblocks in network code.

Location:
uspace/lib/c/generic/inet
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/c/generic/inet/endpoint.c

    r6accc5cf rb10460a  
    3636#include <mem.h>
    3737
     38/** Initialize endpoint structure.
     39 *
     40 * Sets any address, any port number.
     41 *
     42 * @param ep Endpoint
     43 */
    3844void inet_ep_init(inet_ep_t *ep)
    3945{
    … …  
    4147}
    4248
     49/** Initialize endpoint pair structure.
     50 *
     51 * Sets any address, any port number for both local and remote sides.
     52 *
     53 * @param ep2 Endpoint pair
     54 */
    4355void inet_ep2_init(inet_ep2_t *ep2)
    4456{

  • uspace/lib/c/generic/inet/tcp.c

    r6accc5cf rb10460a  
    4444static int tcp_conn_fibril(void *);
    4545
    46 /** Incoming TCP connection info */
     46/** Incoming TCP connection info
     47 *
     48 * Used to pass information about incoming TCP connection to the connection
     49 * fibril
     50 */
    4751typedef struct {
     52        /** Listener who received the connection */
    4853        tcp_listener_t *lst;
     54        /** Incoming connection */
    4955        tcp_conn_t *conn;
    5056} tcp_in_conn_t;
    5157
     58/** Create callback connection from TCP service.
     59 *
     60 * @param tcp TCP service
     61 * @return EOK on success or negative error code
     62 */
    5263static int tcp_callback_create(tcp_t *tcp)
    5364{
    … …  
    6778}
    6879
     80/** Create TCP client instance.
     81 *
     82 * @param  rtcp Place to store pointer to new TCP client
     83 * @return EOK on success, ENOMEM if out of memory, EIO if service
     84 *         cannot be contacted
     85 */
    6986int tcp_create(tcp_t **rtcp)
    7087{
    … …  
    111128}
    112129
     130/** Destroy TCP client instance.
     131 *
     132 * @param tcp TCP client
     133 */
    113134void tcp_destroy(tcp_t *tcp)
    114135{
    … …  
    126147}
    127148
     149/** Create new TCP connection
     150 *
     151 * @param tcp   TCP client instance
     152 * @param id    Connection ID
     153 * @param cb    Callbacks
     154 * @param arg   Callback argument
     155 * @param rconn Place to store pointer to new connection
     156 *
     157 * @return EOK on success, ENOMEM if out of memory
     158 */
    128159static int tcp_conn_new(tcp_t *tcp, sysarg_t id, tcp_cb_t *cb, void *arg,
    129160    tcp_conn_t **rconn)
    … …  
    150181}
    151182
     183/** Create new TCP connection.
     184 *
     185 * Open a connection to the specified destination. This function returns
     186 * even before the connection is established (or not). When the connection
     187 * is established, @a cb->connected is called. If the connection fails,
     188 * @a cb->conn_failed is called. Alternatively, the caller can call
     189 * @c tcp_conn_wait_connected() to wait for connection to complete or fail.
     190 * Other callbacks are available to monitor the changes in connection state.
     191 *
     192 * @a epp must specify the remote address and port. Both local address and
     193 * port are optional. If local address is not specified, address selection
     194 * will take place. If local port number is not specified, a suitable
     195 * free dynamic port number will be allocated.
     196 *
     197 * @param tcp   TCP client
     198 * @param epp   Internet endpoint pair
     199 * @param cb    Callbacks
     200 * @param arg   Argument to callbacks
     201 * @param rconn Place to store pointer to new connection
     202 *
     203 * @return EOK on success or negative error code.
     204 */
    152205int tcp_conn_create(tcp_t *tcp, inet_ep2_t *epp, tcp_cb_t *cb, void *arg,
    153206    tcp_conn_t **rconn)
    … …  
    186239}
    187240
     241/** Destroy TCP connection.
     242 *
     243 * Destroy TCP connection. The caller should destroy all connections
     244 * he created before destroying the TCP client and before terminating.
     245 *
     246 * @param conn TCP connection
     247 */
    188248void tcp_conn_destroy(tcp_conn_t *conn)
    189249{
    … …  
    203263}
    204264
     265/** Get connection based on its ID.
     266 *
     267 * @param tcp   TCP client
     268 * @param id    Connection ID
     269 * @param rconn Place to store pointer to connection
     270 *
     271 * @return EOK on success, EINVAL if no connection with the given ID exists
     272 */
    205273static int tcp_conn_get(tcp_t *tcp, sysarg_t id, tcp_conn_t **rconn)
    206274{
    … …  
    215283}
    216284
     285/** Get the user/callback argument for a connection.
     286 *
     287 * @param conn TCP connection
     288 * @return User argument associated with connection
     289 */
    217290void *tcp_conn_userptr(tcp_conn_t *conn)
    218291{
    … …  
    220293}
    221294
     295/** Create a TCP connection listener.
     296 *
     297 * A listener listens for connections on the set of endpoints specified
     298 * by @a ep. Each time a new incoming connection is established,
     299 * @a lcb->new_conn is called (and passed @a larg). Also, the new connection
     300 * will have callbacks set to @a cb and argument to @a arg.
     301 *
     302 * @a ep must specify a valid port number. @a ep may specify an address
     303 * or link to listen on. If it does not, the listener will listen on
     304 * all links/addresses.
     305 *
     306 * @param tcp  TCP client
     307 * @param ep   Internet endpoint
     308 * @param lcb  Listener callbacks
     309 * @param larg Listener callback argument
     310 * @param cb   Connection callbacks for every new connection
     311 * @param arg  Connection argument for every new connection
     312 * @param rlst Place to store pointer to new listener
     313 *
     314 * @return EOK on success or negative error code
     315 */
    222316int tcp_listener_create(tcp_t *tcp, inet_ep_t *ep, tcp_listen_cb_t *lcb,
    223317    void *larg, tcp_cb_t *cb, void *arg, tcp_listener_t **rlst)
    … …  
    265359}
    266360
     361/** Destroy TCP connection listener.
     362 *
     363 * @param lst Listener
     364 */
    267365void tcp_listener_destroy(tcp_listener_t *lst)
    268366{
    … …  
    282380}
    283381
     382/** Get TCP connection listener based on its ID.
     383 *
     384 * @param tcp TCP client
     385 * @param id  Listener ID
     386 * @param rlst Place to store pointer to listener
     387 *
     388 * @return EOK on success, EINVAL if no listener with the given ID is found
     389 */
    284390static int tcp_listener_get(tcp_t *tcp, sysarg_t id, tcp_listener_t **rlst)
    285391{
    … …  
    294400}
    295401
     402/** Get callback/user argument associated with listener.
     403 *
     404 * @param lst Listener
     405 * @return Callback/user argument
     406 */
    296407void *tcp_listener_userptr(tcp_listener_t *lst)
    297408{
    … …  
    299410}
    300411
     412/** Wait until connection is either established or connection fails.
     413 *
     414 * Can be called after calling tcp_conn_create() to block until connection
     415 * either completes or fails. If the connection fails, EIO is returned.
     416 * In this case the connection still exists, but is in a failed
     417 * state.
     418 *
     419 * @param conn Connection
     420 * @return EOK if connection is established, EIO otherwise
     421 */
    301422int tcp_conn_wait_connected(tcp_conn_t *conn)
    302423{
    … …  
    315436}
    316437
     438/** Send data over TCP connection.
     439 *
     440 * @param conn  Connection
     441 * @param data  Data
     442 * @param bytes Data size in bytes
     443 *
     444 * @return EOK on success or negative error code
     445 */
    317446int tcp_conn_send(tcp_conn_t *conn, const void *data, size_t bytes)
    318447{
    … …  
    340469}
    341470
    342 
     471/** Send FIN.
     472 *
     473 * Send FIN, indicating no more data will be send over the connection.
     474 *
     475 * @param conn Connection
     476 * @return EOK on success or negative error code
     477 */
    343478int tcp_conn_send_fin(tcp_conn_t *conn)
    344479{
    … …  
    352487}
    353488
     489/** Push connection.
     490 *
     491 * @param conn Connection
     492 * @return EOK on success or negative error code
     493 */
    354494int tcp_conn_push(tcp_conn_t *conn)
    355495{
    … …  
    363503}
    364504
     505/** Reset connection.
     506 *
     507 * @param conn Connection
     508 * @return EOK on success or negative error code
     509 */
    365510int tcp_conn_reset(tcp_conn_t *conn)
    366511{
    … …  
    374519}
    375520
     521/** Read received data from connection without blocking.
     522 *
     523 * If any received data is pending on the connection, up to @a bsize bytes
     524 * are copied to @a buf and the acutal number is stored in @a *nrecv.
     525 * The entire buffer of @a bsize bytes is filled except when less data
     526 * is currently available or FIN is received. EOK is returned.
     527 *
     528 * If no received data is pending, returns EAGAIN.
     529 *
     530 * @param conn Connection
     531 * @param buf  Buffer
     532 * @param bsize Buffer size
     533 * @param nrecv Place to store actual number of received bytes
     534 *
     535 * @return EOK on success, EAGAIN if no received data is pending, or other
     536 *         negative error code in case of other error
     537 */
    376538int tcp_conn_recv(tcp_conn_t *conn, void *buf, size_t bsize, size_t *nrecv)
    377539{
    … …  
    408570}
    409571
    410 int tcp_conn_recv_wait(tcp_conn_t *conn, void *buf, size_t bsize, size_t *nrecv)
     572/** Read received data from connection with blocking.
     573 *
     574 * Wait for @a bsize bytes of data to be received and copy them to
     575 * @a buf. Less data may be returned if FIN is received on the connection.
     576 * The actual If any received data is written to @a *nrecv and EOK
     577 * is returned on success.
     578 *
     579 * @param conn Connection
     580 * @param buf  Buffer
     581 * @param bsize Buffer size
     582 * @param nrecv Place to store actual number of received bytes
     583 *
     584 * @return EOK on success or negative error code
     585 */
     586int tcp_conn_recv_wait(tcp_conn_t *conn, void *buf, size_t bsize,
     587    size_t *nrecv)
    411588{
    412589        async_exch_t *exch;
    … …  
    450627}
    451628
     629/** Connection established event.
     630 *
     631 * @param tcp TCP client
     632 * @param iid Call ID
     633 * @param icall Call data
     634 */
    452635static void tcp_ev_connected(tcp_t *tcp, ipc_callid_t iid, ipc_call_t *icall)
    453636{
    … …  
    472655}
    473656
     657/** Connection failed event.
     658 *
     659 * @param tcp TCP client
     660 * @param iid Call ID
     661 * @param icall Call data
     662 */
    474663static void tcp_ev_conn_failed(tcp_t *tcp, ipc_callid_t iid, ipc_call_t *icall)
    475664{
    … …  
    494683}
    495684
     685/** Connection reset event.
     686 *
     687 * @param tcp TCP client
     688 * @param iid Call ID
     689 * @param icall Call data
     690 */
    496691static void tcp_ev_conn_reset(tcp_t *tcp, ipc_callid_t iid, ipc_call_t *icall)
    497692{
    … …  
    516711}
    517712
     713/** Data available event.
     714 *
     715 * @param tcp TCP client
     716 * @param iid Call ID
     717 * @param icall Call data
     718 */
    518719static void tcp_ev_data(tcp_t *tcp, ipc_callid_t iid, ipc_call_t *icall)
    519720{
    … …  
    539740}
    540741
     742/** Urgent data event.
     743 *
     744 * @param tcp TCP client
     745 * @param iid Call ID
     746 * @param icall Call data
     747 */
    541748static void tcp_ev_urg_data(tcp_t *tcp, ipc_callid_t iid, ipc_call_t *icall)
    542749{
    … …  
    544751}
    545752
     753/** New connection event.
     754 *
     755 * @param tcp TCP client
     756 * @param iid Call ID
     757 * @param icall Call data
     758 */
    546759static void tcp_ev_new_conn(tcp_t *tcp, ipc_callid_t iid, ipc_call_t *icall)
    547760{
    … …  
    590803}
    591804
     805/** Callback connection handler.
     806 *
     807 * @param iid Connect call ID
     808 * @param icall Connect call data
     809 * @param arg Argument, TCP client
     810 */
    592811static void tcp_cb_conn(ipc_callid_t iid, ipc_call_t *icall, void *arg)
    593812{
    … …  
    636855}
    637856
    638 /** Fibril for handling incoming TCP connection in background */
     857/** Fibril for handling incoming TCP connection in background.
     858 *
     859 * @param arg Argument, incoming connection information (@c tcp_in_conn_t)
     860 */
    639861static int tcp_conn_fibril(void *arg)
    640862{

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

    r6accc5cf rb10460a  
    4343static void udp_cb_conn(ipc_callid_t, ipc_call_t *, void *);
    4444
     45/** Create callback connection from UDP service.
     46 *
     47 * @param udp UDP service
     48 * @return EOK on success or negative error code
     49 */
    4550static int udp_callback_create(udp_t *udp)
    4651{
    … …  
    6065}
    6166
     67/** Create UDP client instance.
     68 *
     69 * @param  rudp Place to store pointer to new UDP client
     70 * @return EOK on success, ENOMEM if out of memory, EIO if service
     71 *         cannot be contacted
     72 */
    6273int udp_create(udp_t **rudp)
    6374{
    … …  
    103114}
    104115
     116/** Destroy UDP client instance.
     117 *
     118 * @param udp UDP client
     119 */
    105120void udp_destroy(udp_t *udp)
    106121{
    … …  
    118133}
    119134
    120 int udp_assoc_create(udp_t *udp, inet_ep2_t *ep2, udp_cb_t *cb, void *arg,
     135/** Create new UDP association.
     136 *
     137 * Create a UDP association that allows sending and receiving messages.
     138 *
     139 * @a epp may specify remote address and port, in which case only messages
     140 * from that remote endpoint will be received. Also, that remote endpoint
     141 * is used as default when @c NULL is passed as destination to
     142 * udp_assoc_send_msg.
     143 *
     144 * @a epp may specify a local link or address. If it does not, the association
     145 * will listen on all local links/addresses. If @a epp does not specify
     146 * a local port number, a free dynamic port number will be allocated.
     147 *
     148 * The caller is informed about incoming data by invoking @a cb->recv_msg
     149 *
     150 * @param udp    UDP client
     151 * @param epp    Internet endpoint pair
     152 * @param cb     Callbacks
     153 * @param arg    Argument to callbacks
     154 * @param rassoc Place to store pointer to new association
     155 *
     156 * @return EOK on success or negative error code.
     157 */
     158int udp_assoc_create(udp_t *udp, inet_ep2_t *epp, udp_cb_t *cb, void *arg,
    121159    udp_assoc_t **rassoc)
    122160{
    … …  
    131169        exch = async_exchange_begin(udp->sess);
    132170        aid_t req = async_send_0(exch, UDP_ASSOC_CREATE, &answer);
    133         sysarg_t rc = async_data_write_start(exch, (void *)ep2,
     171        sysarg_t rc = async_data_write_start(exch, (void *)epp,
    134172            sizeof(inet_ep2_t));
    135173        async_exchange_end(exch);
    … …  
    161199}
    162200
     201/** Destroy UDP association.
     202 *
     203 * Destroy UDP association. The caller should destroy all associations
     204 * he created before destroying the UDP client and before terminating.
     205 *
     206 * @param assoc UDP association
     207 */
    163208void udp_assoc_destroy(udp_assoc_t *assoc)
    164209{
    … …  
    178223}
    179224
     225/** Send message via UDP association.
     226 *
     227 * @param assoc Association
     228 * @param dest  Destination endpoint or @c NULL to use association's remote ep.
     229 * @param data  Message data
     230 * @param bytes Message size in bytes
     231 *
     232 * @return EOK on success or negative error code
     233 */
    180234int udp_assoc_send_msg(udp_assoc_t *assoc, inet_ep_t *dest, void *data,
    181235    size_t bytes)
    … …  
    211265}
    212266
     267/** Get the user/callback argument for an association.
     268 *
     269 * @param assoc UDP association
     270 * @return User argument associated with association
     271 */
    213272void *udp_assoc_userptr(udp_assoc_t *assoc)
    214273{
    … …  
    216275}
    217276
     277/** Get size of received message in bytes.
     278 *
     279 * Assuming jumbo messages can be received, the caller first needs to determine
     280 * the size of the received message by calling this function, then they can
     281 * read the message piece-wise using udp_rmsg_read().
     282 *
     283 * @param rmsg Received message
     284 * @return Size of received message in bytes
     285 */
    218286size_t udp_rmsg_size(udp_rmsg_t *rmsg)
    219287{
    … …  
    221289}
    222290
     291/** Read part of received message.
     292 *
     293 * @param rmsg  Received message
     294 * @param off   Start offset
     295 * @param buf   Buffer for storing data
     296 * @param bsize Buffer size
     297 *
     298 * @return EOK on success or negative error code.
     299 */
    223300int udp_rmsg_read(udp_rmsg_t *rmsg, size_t off, void *buf, size_t bsize)
    224301{
    … …  
    245322}
    246323
     324/** Get remote endpoint of received message.
     325 *
     326 * Place the remote endpoint (the one from which the message was supposedly
     327 * sent) to @a ep.
     328 *
     329 * @param rmsg Received message
     330 * @param ep   Place to store remote endpoint
     331 */
    247332void udp_rmsg_remote_ep(udp_rmsg_t *rmsg, inet_ep_t *ep)
    248333{
    … …  
    250335}
    251336
     337/** Get type of received ICMP error message.
     338 *
     339 * @param rerr Received error message
     340 * @return Error message type
     341 */
    252342uint8_t udp_rerr_type(udp_rerr_t *rerr)
    253343{
    … …  
    255345}
    256346
     347/** Get code of received ICMP error message.
     348 *
     349 * @param rerr Received error message
     350 * @return Error message code
     351 */
    257352uint8_t udp_rerr_code(udp_rerr_t *rerr)
    258353{
    … …  
    260355}
    261356
     357/** Get information about the next received message from UDP service.
     358 *
     359 * @param udp  UDP client
     360 * @param rmsg Place to store message information
     361 *
     362 * @return EOK on success or negative error code
     363 */
    262364static int udp_rmsg_info(udp_t *udp, udp_rmsg_t *rmsg)
    263365{
    … …  
    288390}
    289391
     392/** Discard next received message in UDP service.
     393 *
     394 * @param udp UDP client
     395 * @return EOK on success or negative error code
     396 */
    290397static int udp_rmsg_discard(udp_t *udp)
    291398{
    … …  
    299406}
    300407
     408/** Get association based on its ID.
     409 *
     410 * @param udp    UDP client
     411 * @param id     Association ID
     412 * @param rassoc Place to store pointer to association
     413 *
     414 * @return EOK on success, EINVAL if no association with the given ID exists
     415 */
    301416static int udp_assoc_get(udp_t *udp, sysarg_t id, udp_assoc_t **rassoc)
    302417{
    … …  
    311426}
    312427
     428/** Handle 'data' event, i.e. some message(s) arrived.
     429 *
     430 * For each received message, get information about it, call @c recv_msg
     431 * callback and discard it.
     432 *
     433 * @param udp UDP client
     434 * @param iid IPC message ID
     435 * @param icall IPC message
     436 */
    313437static void udp_ev_data(udp_t *udp, ipc_callid_t iid, ipc_call_t *icall)
    314438{
    … …  
    340464}
    341465
     466/** UDP service callback connection.
     467 *
     468 * @param iid Connect message ID
     469 * @param icall Connect message
     470 * @param arg Argument, UDP client
     471 */
    342472static void udp_cb_conn(ipc_callid_t iid, ipc_call_t *icall, void *arg)
    343473{
Note: See TracChangeset for help on using the changeset viewer.