← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/virtualbox-ose/gutsy

« back to all changes in this revision

Viewing changes to include/iprt/tcp.h

  • Committer: Bazaar Package Importer
  • Author(s): Steve Kowalik
  • Date: 2007-09-08 16:44:58 UTC
  • Revision ID: james.westby@ubuntu.com-20070908164458-wao29470vqtr8ksy
Tags: upstream-1.5.0-dfsg2
Import upstream version 1.5.0-dfsg2

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/iprt/tcp.h
 
1
/** @file
 
2
 * innotek Portable Runtime - TCP/IP.
 
3
 */
 
4
 
 
5
/*
 
6
 * Copyright (C) 2006-2007 innotek GmbH
 
7
 *
 
8
 * This file is part of VirtualBox Open Source Edition (OSE), as
 
9
 * available from http://www.virtualbox.org. This file is free software;
 
10
 * you can redistribute it and/or modify it under the terms of the GNU
 
11
 * General Public License as published by the Free Software Foundation,
 
12
 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
 
13
 * distribution. VirtualBox OSE is distributed in the hope that it will
 
14
 * be useful, but WITHOUT ANY WARRANTY of any kind.
 
15
 */
 
16
 
 
17
#ifndef ___iprt_tcp_h
 
18
#define ___iprt_tcp_h
 
19
 
 
20
#include <iprt/cdefs.h>
 
21
#include <iprt/types.h>
 
22
#include <iprt/thread.h>
 
23
 
 
24
#ifdef IN_RING0
 
25
# error "There are no RTFile APIs available Ring-0 Host Context!"
 
26
#endif
 
27
 
 
28
 
 
29
__BEGIN_DECLS
 
30
 
 
31
/** @defgroup grp_rt_tcp    RTTcp - TCP/IP
 
32
 * @ingroup grp_rt
 
33
 * @{
 
34
 */
 
35
 
 
36
 
 
37
/**
 
38
 * Serve a TCP Server connection.
 
39
 *
 
40
 * @returns iprt status code.
 
41
 * @returns VERR_TCP_SERVER_STOP to terminate the server loop forcing
 
42
 *          the RTTcpCreateServer() call to return.
 
43
 * @param   Sock        The socket which the client is connected to.
 
44
 *                      The call will close this socket.
 
45
 * @param   pvUser      User argument.
 
46
 */
 
47
typedef DECLCALLBACK(int) FNRTTCPSERVE(RTSOCKET Sock, void *pvUser);
 
48
/** Pointer to a RTTCPSERVE(). */
 
49
typedef FNRTTCPSERVE *PFNRTTCPSERVE;
 
50
 
 
51
/** Pointer to a RTTCPSERVER handle. */
 
52
typedef struct RTTCPSERVER *PRTTCPSERVER;
 
53
/** Pointer to a RTTCPSERVER handle. */
 
54
typedef PRTTCPSERVER *PPRTTCPSERVER;
 
55
 
 
56
/**
 
57
 * Create single connection at a time TCP Server in a separate thread.
 
58
 *
 
59
 * The thread will loop accepting connections and call pfnServe for
 
60
 * each of the incoming connections in turn. The pfnServe function can
 
61
 * return VERR_TCP_SERVER_STOP too terminate this loop. RTTcpServerDestroy()
 
62
 * should be used to terminate the server.
 
63
 *
 
64
 * @returns iprt status code.
 
65
 * @param   pszAddress      The address for creating a listening socket.
 
66
 *                          If NULL or empty string the server is bound to all interfaces.
 
67
 * @param   uPort           The port for creating a listening socket.
 
68
 * @param   enmType         The thread type.
 
69
 * @param   pszThrdName     The name of the worker thread.
 
70
 * @param   pfnServe        The function which will serve a new client connection.
 
71
 * @param   pvUser          User argument passed to pfnServe.
 
72
 * @param   ppServer        Where to store the serverhandle.
 
73
 */
 
74
RTR3DECL(int)  RTTcpServerCreate(const char *pszAddress, unsigned uPort, RTTHREADTYPE enmType, const char *pszThrdName,
 
75
                                 PFNRTTCPSERVE pfnServe, void *pvUser, PPRTTCPSERVER ppServer);
 
76
 
 
77
/**
 
78
 * Create single connection at a time TCP Server.
 
79
 * The caller must call RTTcpServerListen() to actually start the server.
 
80
 *
 
81
 * @returns iprt status code.
 
82
 * @param   pszAddress      The address for creating a listening socket.
 
83
 *                          If NULL the server is bound to all interfaces.
 
84
 * @param   uPort           The port for creating a listening socket.
 
85
 * @param   ppServer        Where to store the serverhandle.
 
86
 */
 
87
RTR3DECL(int) RTTcpServerCreateEx(const char *pszAddress, uint32_t uPort, PPRTTCPSERVER ppServer);
 
88
 
 
89
/**
 
90
 * Closes down and frees a TCP Server.
 
91
 * This will also terminate any open connections to the server.
 
92
 *
 
93
 * @returns iprt status code.
 
94
 * @param   pServer         Handle to the server.
 
95
 */
 
96
RTR3DECL(int) RTTcpServerDestroy(PRTTCPSERVER pServer);
 
97
 
 
98
/**
 
99
 * Listen for incoming connections.
 
100
 *
 
101
 * The function will loop accepting connections and call pfnServe for
 
102
 * each of the incoming connections in turn. The pfnServe function can
 
103
 * return VERR_TCP_SERVER_STOP too terminate this loop. A stopped server
 
104
 * can only be destroyed.
 
105
 *
 
106
 * @returns iprt status code.
 
107
 * @param   pServer         The server handle as returned from RTTcpServerCreateEx().
 
108
 * @param   pfnServe        The function which will serve a new client connection.
 
109
 * @param   pvUser          User argument passed to pfnServe.
 
110
 */
 
111
RTR3DECL(int) RTTcpServerListen(PRTTCPSERVER pServer, PFNRTTCPSERVE pfnServe, void *pvUser);
 
112
 
 
113
/**
 
114
 * Terminate the open connection to the server.
 
115
 *
 
116
 * @returns iprt status code.
 
117
 * @param   pServer         Handle to the server.
 
118
 */
 
119
RTR3DECL(int) RTTcpServerDisconnectClient(PRTTCPSERVER pServer);
 
120
 
 
121
/**
 
122
 * Connect (as a client) to a TCP Server.
 
123
 *
 
124
 * @returns iprt status code.
 
125
 * @param   pszAddress      The address to connect to.
 
126
 * @param   uPort           The port to connect to.
 
127
 * @param   pSock           Where to store the handle to the established connection.
 
128
 */
 
129
RTR3DECL(int) RTTcpClientConnect(const char *pszAddress, uint32_t uPort, PRTSOCKET pSock);
 
130
 
 
131
/**
 
132
 * Close a socket returned by RTTcpClientConnect().
 
133
 *
 
134
 * @returns iprt status code.
 
135
 * @param   Sock        Socket descriptor.
 
136
 */
 
137
RTR3DECL(int) RTTcpClientClose(RTSOCKET Sock);
 
138
 
 
139
/**
 
140
 * Receive data from a socket.
 
141
 *
 
142
 * @returns iprt status code.
 
143
 * @param   Sock        Socket descriptor.
 
144
 * @param   pvBuffer    Where to put the data we read.
 
145
 * @param   cbBuffer    Read buffer size.
 
146
 * @param   pcbRead     Number of bytes read.
 
147
 *                      If NULL the entire buffer will be filled upon successful return.
 
148
 *                      If not NULL a partial read can be done successfully.
 
149
 */
 
150
RTR3DECL(int)  RTTcpRead(RTSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead);
 
151
 
 
152
/**
 
153
 * Send data from a socket.
 
154
 *
 
155
 * @returns iprt status code.
 
156
 * @param   Sock        Socket descriptor.
 
157
 * @param   pvBuffer    Buffer to write data to socket.
 
158
 * @param   cbBuffer    How much to write.
 
159
 */
 
160
RTR3DECL(int)  RTTcpWrite(RTSOCKET Sock, const void *pvBuffer, size_t cbBuffer);
 
161
 
 
162
/**
 
163
 * Flush socket write buffers.
 
164
 *
 
165
 * @returns iprt status code.
 
166
 * @param   Sock        Socket descriptor.
 
167
 */
 
168
RTR3DECL(int)  RTTcpFlush(RTSOCKET Sock);
 
169
 
 
170
/**
 
171
 * Socket I/O multiplexing.
 
172
 * Checks if the socket is ready for reading.
 
173
 *
 
174
 * @returns iprt status code.
 
175
 * @param   Sock        Socket descriptor.
 
176
 * @param   cMillies    Number of milliseconds to wait for the socket.
 
177
 *                      Use RT_INDEFINITE_WAIT to wait for ever.
 
178
 */
 
179
RTR3DECL(int)  RTTcpSelectOne(RTSOCKET Sock, unsigned cMillies);
 
180
 
 
181
 
 
182
#if 0 /* skipping these for now - RTTcpServer* handles this. */
 
183
/**
 
184
 * Listen for connection on a socket.
 
185
 *
 
186
 * @returns iprt status code.
 
187
 * @param   Sock        Socket descriptor.
 
188
 * @param   cBackLog    The maximum length the queue of pending connections
 
189
 *                      may grow to.
 
190
 */
 
191
RTR3DECL(int)  RTTcpListen(RTSOCKET Sock, int cBackLog);
 
192
 
 
193
/**
 
194
 * Accept a connection on a socket.
 
195
 *
 
196
 * @returns iprt status code.
 
197
 * @param   Sock            Socket descriptor.
 
198
 * @param   uPort           The port for accepting connection.
 
199
 * @param   pSockAccepted   Where to store the handle to the accepted connection.
 
200
 */
 
201
RTR3DECL(int)  RTTcpAccept(RTSOCKET Sock, unsigned uPort, PRTSOCKET pSockAccepted);
 
202
 
 
203
#endif
 
204
 
 
205
 
 
206
/** @} */
 
207
__END_DECLS
 
208
 
 
209
#endif
 
210