diff options
author | Samuel Thibault <samuel.thibault@ens-lyon.org> | 2021-02-11 14:43:38 +0100 |
---|---|---|
committer | Samuel Thibault <samuel.thibault@ens-lyon.org> | 2021-02-11 14:43:38 +0100 |
commit | 110988742fee2adb81ceb5d2895f26fd0a5aeefe (patch) | |
tree | 8c64cb27c63a18d2992f6545afd8390b4ef68818 | |
parent | 52c9f8de676aeca5f13ffc752b7b2097493b1c72 (diff) | |
download | slirp-110988742fee2adb81ceb5d2895f26fd0a5aeefe.zip slirp-110988742fee2adb81ceb5d2895f26fd0a5aeefe.tar.gz slirp-110988742fee2adb81ceb5d2895f26fd0a5aeefe.tar.bz2 |
Document the slirp API
-rw-r--r-- | src/libslirp.h | 64 |
1 files changed, 55 insertions, 9 deletions
diff --git a/src/libslirp.h b/src/libslirp.h index 280d3d0..8862259 100644 --- a/src/libslirp.h +++ b/src/libslirp.h @@ -20,8 +20,10 @@ extern "C" { #endif +/* Opaque structure containing the slirp state */ typedef struct Slirp Slirp; +/* Flags passed to SlirpAddPollCb and to be returned by SlirpGetREventsCb. */ enum { SLIRP_POLL_IN = 1 << 0, SLIRP_POLL_OUT = 1 << 1, @@ -37,7 +39,10 @@ typedef int (*SlirpAddPollCb)(int fd, int events, void *opaque); typedef int (*SlirpGetREventsCb)(int idx, void *opaque); /* - * Callbacks from slirp + * Callbacks from slirp, to be set by the application. + * + * The opaque parameter is set to the opaque pointer given in the slirp_new / + * slirp_init call. */ typedef struct SlirpCb { /* @@ -115,6 +120,7 @@ typedef struct SlirpConfig { bool disable_dns; /* slirp will not redirect/serve any DNS packet */ } SlirpConfig; +/* Create a new instance of a slirp stack */ Slirp *slirp_new(const SlirpConfig *cfg, const SlirpCb *callbacks, void *opaque); /* slirp_init is deprecated in favor of slirp_new */ @@ -128,16 +134,34 @@ Slirp *slirp_init(int restricted, bool in_enabled, struct in_addr vnetwork, struct in6_addr vnameserver6, const char **vdnssearch, const char *vdomainname, const SlirpCb *callbacks, void *opaque); +/* Shut down an instance of a slirp stack */ void slirp_cleanup(Slirp *slirp); +/* This is called by the application when it is about to sleep through poll(). + * *timeout is set to the amount of virtual time that the application intends to + * wait (UINT32_MAX if infinite). slirp_pollfds_fill updates it according to + * e.g. TCP timers, so the application knows it should sleep a smaller amount of + * time. slirp_pollfds_fill calls add_poll for each file descriptor + * that should be monitored along the sleep. The opaque pointer is passed as + * such to add_poll, and add_poll returns an index. */ void slirp_pollfds_fill(Slirp *slirp, uint32_t *timeout, SlirpAddPollCb add_poll, void *opaque); +/* This is called by the application after sleeping, to report which file + * descriptors are available. slirp_pollfds_poll calls get_revents on each file + * descriptor, giving it the index that add_poll returned during the + * slirp_pollfds_fill call, to know whether the descriptor is available for + * read/write/etc. (SLIRP_POLL_*) + * select_error should be passed 1 if poll() returned an error. */ void slirp_pollfds_poll(Slirp *slirp, int select_error, SlirpGetREventsCb get_revents, void *opaque); +/* This is called by the application when the guest emits a packet on the + * guest network, to be interpreted by slirp. */ void slirp_input(Slirp *slirp, const uint8_t *pkt, int pkt_len); +/* These set up / remove port forwarding between a host port in the real world + * and the guest network. */ int slirp_add_hostfwd(Slirp *slirp, int is_udp, struct in_addr host_addr, int host_port, struct in_addr guest_addr, int guest_port); int slirp_remove_hostfwd(Slirp *slirp, int is_udp, struct in_addr host_addr, @@ -148,30 +172,52 @@ int slirp_add_ipv6_hostfwd(Slirp *slirp, int is_udp, int slirp_remove_ipv6_hostfwd(Slirp *slirp, int is_udp, struct in6_addr host_addr, int host_port); +/* Set up port forwarding between a port in the guest network and a + * command running on the host */ int slirp_add_exec(Slirp *slirp, const char *cmdline, struct in_addr *guest_addr, int guest_port); +/* Set up port forwarding between a port in the guest network and a + * Unix port on the host */ int slirp_add_unix(Slirp *slirp, const char *unixsock, struct in_addr *guest_addr, int guest_port); +/* Set up port forwarding between a port in the guest network and a + * callback that will receive the data coming from the port */ int slirp_add_guestfwd(Slirp *slirp, SlirpWriteCb write_cb, void *opaque, struct in_addr *guest_addr, int guest_port); -/* remove entries added by slirp_add_exec, slirp_add_unix or slirp_add_guestfwd */ -int slirp_remove_guestfwd(Slirp *slirp, struct in_addr guest_addr, - int guest_port); -char *slirp_connection_info(Slirp *slirp); +/* TODO: rather identify a guestfwd through an opaque pointer instead of through + * the guest_addr */ -void slirp_socket_recv(Slirp *slirp, struct in_addr guest_addr, int guest_port, - const uint8_t *buf, int size); +/* This is called by the application for a guestfwd, to determine how much data + * can be received by the forwarded port through a call to slirp_socket_recv. */ size_t slirp_socket_can_recv(Slirp *slirp, struct in_addr guest_addr, int guest_port); +/* This is called by the application for a guestfwd, to provide the data to be + * sent on the forwarded port */ +void slirp_socket_recv(Slirp *slirp, struct in_addr guest_addr, int guest_port, + const uint8_t *buf, int size); + +/* Remove entries added by slirp_add_exec, slirp_add_unix or slirp_add_guestfwd */ +int slirp_remove_guestfwd(Slirp *slirp, struct in_addr guest_addr, + int guest_port); + +/* Return a human-readable state of the slirp stack */ +char *slirp_connection_info(Slirp *slirp); +/* Save the slirp state through the write_cb. The opaque pointer is passed as + * such to the write_cb. */ void slirp_state_save(Slirp *s, SlirpWriteCb write_cb, void *opaque); +/* Returns the version of the slirp state, to be saved along the state */ +int slirp_state_version(void); + +/* Load the slirp state through the read_cb. The opaque pointer is passed as + * such to the read_cb. The version should be given as it was obtained from + * slirp_state_version when slirp_state_save was called. */ int slirp_state_load(Slirp *s, int version_id, SlirpReadCb read_cb, void *opaque); -int slirp_state_version(void); - +/* Return the version of the slirp implementation */ const char *slirp_version_string(void); #ifdef __cplusplus |