Version bumps after new release
[alexxy/gromacs.git] / src / gromacs / imd / imdsocket.h
1 /*
2  * This file is part of the GROMACS molecular simulation package.
3  *
4  * Copyright (c) 2014, by the GROMACS development team, led by
5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
6  * and including many others, as listed in the AUTHORS file in the
7  * top-level source directory and at http://www.gromacs.org.
8  *
9  * GROMACS is free software; you can redistribute it and/or
10  * modify it under the terms of the GNU Lesser General Public License
11  * as published by the Free Software Foundation; either version 2.1
12  * of the License, or (at your option) any later version.
13  *
14  * GROMACS is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17  * Lesser General Public License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public
20  * License along with GROMACS; if not, see
21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
23  *
24  * If you want to redistribute modifications to GROMACS, please
25  * consider that scientific software is very special. Version
26  * control is crucial - bugs must be traceable. We will be happy to
27  * consider code for inclusion in the official distribution, but
28  * derived work must not be called official GROMACS. Details are found
29  * in the README & COPYING files - if they are missing, get the
30  * official version at http://www.gromacs.org.
31  *
32  * To help us fund GROMACS development, we humbly ask that you cite
33  * the research papers on the package. Check out http://www.gromacs.org.
34  */
35
36 /*! \libinternal \file
37  *
38  * \brief
39  * Implements the parts of the vmdsock.h interface needed for IMD communication.
40  *
41  * \author Martin Hoefling, Carsten Kutzner <ckutzne@gwdg.de>
42  *
43  * For more information, see https://www-s.ks.uiuc.edu/Research/vmd/imd/ for general
44  * IMD information and https://www-s.ks.uiuc.edu/Research/vmd/imd/code/imdapi.tar.gz
45  * for the IMD reference implementation and API.
46  *
47  * \inlibraryapi
48  * \ingroup module_imd
49  */
50
51 #ifndef GMX_IMD_IMDSOCKET_H
52 #define GMX_IMD_IMDSOCKET_H
53
54 /* Check if we can/should use winsock or standard UNIX sockets. */
55 #ifdef GMX_NATIVE_WINDOWS
56   #ifdef GMX_HAVE_WINSOCK
57   #include <Winsock.h>
58   #define GMX_IMD
59   #endif
60 #else
61 #include <sys/socket.h>
62 #include <netinet/in.h>
63 #define GMX_IMD
64 #endif
65
66
67 #ifdef __cplusplus
68 extern "C" {
69 #endif
70
71
72
73 /*! \internal
74  *
75  * \brief
76  * IMD (interactive molecular dynamics) socket structure
77  *
78  */
79 typedef struct
80 {
81 #ifdef GMX_IMD
82     struct sockaddr_in address;      /**< address of socket                   */
83 #endif
84     int                sockfd;       /**< socket file descriptor              */
85 } IMDSocket;
86
87
88
89 #if defined(GMX_NATIVE_WINDOWS) && defined(GMX_HAVE_WINSOCK)
90 /*! \internal
91  *
92  * \brief Function to initialize winsock
93  *
94  * \returns 0 if successful.
95  */
96 extern int imdsock_winsockinit();
97 #endif
98
99
100 /*! \brief Create an IMD master socket.
101  *
102  * \returns  The IMD socket if successful. Otherwise prints an error message and returns NULL.
103  */
104 extern IMDSocket *imdsock_create();
105
106
107 /*! \brief Bind the IMD socket to address and port.
108  *
109  * Prints out an error message if unsuccessful.
110  * If port == 0, bind() assigns a free port automatically.
111  *
112  *
113  * \param sock      The IMD socket.
114  * \param port      The port to bind to.
115  *
116  * \returns 0 if successful.
117  */
118 extern int imdsock_bind(IMDSocket *sock, int port);
119
120
121 /*! \brief Set socket to listening state.
122  *
123  * Prints out an error message if unsuccessful.
124  *
125  * \param sock      The IMD socket.
126  *
127  * \returns 0 if successful.
128  *
129  */
130 extern int imd_sock_listen(IMDSocket *sock);
131
132
133 /*! \brief Accept incoming connection and redirect to client socket.
134  *
135  * Prints out an error message if unsuccessful.
136  *
137  * \param sock      The IMD socket.
138  *
139  * \returns IMD socket if successful, NULL otherwise.
140  */
141 extern IMDSocket *imdsock_accept(IMDSocket *sock);
142
143
144 /*! \brief Get the port number used for IMD connection.
145  *
146  * Prints out an error message if unsuccessful.
147  *
148  * \param sock      The IMD socket.
149  * \param port      The assigned port number.
150  *
151  * \returns 0 if successful, an error code otherwise.
152  */
153 extern int imdsock_getport(IMDSocket *sock, int *port);
154
155
156 /*! \brief  Write to socket.
157  *
158  *
159  * \param sock      The IMD socket.
160  * \param buffer    The data to write.
161  * \param length    Number of bytes to write.
162  *
163  * \returns The number of bytes written, or -1.
164  */
165 extern int imdsock_write(IMDSocket *sock, const char *buffer, int length);
166
167
168 /*! \brief  Read from socket.
169  *
170  * \param sock      The IMD socket.
171  * \param buffer    Buffer to put the read data.
172  * \param length    Number of bytes to read.
173  *
174  * \returns The number of bytes read, or -1 for errors.
175  */
176 extern int imdsock_read(IMDSocket *sock, char *buffer, int length);
177
178
179 /*! \brief Shutdown the socket.
180  *
181  * \param sock      The IMD socket.
182  *
183  */
184 extern void imdsock_shutdown(IMDSocket *sock);
185
186
187 /*! \brief Close the socket and free the sock struct memory.
188  *
189  * Writes an error message if unsuccessful.
190  *
191  * \param sock      The IMD socket.
192  *
193  * \returns 1 on success, or 0 if unsuccessful.
194  */
195 extern int imdsock_destroy(IMDSocket *sock);
196
197
198 /*! \brief Try to read from the socket.
199  *
200  * Time out after waiting the interval specified.
201  * Print an error message if unsuccessful.
202  *
203  * \param sock         The IMD socket.
204  * \param timeoutsec   Time out seconds
205  * \param timeoutusec  Time out microseconds
206  *
207  */
208 extern int imdsock_tryread(IMDSocket *sock, int timeoutsec, int timeoutusec);
209
210
211 #ifdef __cplusplus
212 }
213 #endif
214
215
216 #endif