1// Copyright (c) 2011 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4// Written in NSPR style to also be suitable for adding to the NSS demo suite
5
6#ifndef __MEMIO_H
7#define __MEMIO_H
8
9#include <stddef.h>
10
11#ifdef __cplusplus
12extern "C" {
13#endif
14
15#include "prio.h"
16
17/* Opaque structure.  Really just a more typesafe alias for PRFilePrivate. */
18struct memio_Private;
19typedef struct memio_Private memio_Private;
20
21/*----------------------------------------------------------------------
22 NSPR I/O layer that terminates in a pair of circular buffers
23 rather than talking to the real network.
24 To use this with NSS:
25 1) call memio_CreateIOLayer to create a fake NSPR socket
26 2) call SSL_ImportFD to ssl-ify the socket
27 3) Do your own networking calls to set up a TCP connection
28 4) call memio_SetPeerName to tell NSS about the other end of the connection
29 5) While at the same time doing plaintext nonblocking NSPR I/O as
30    usual to the nspr file descriptor returned by SSL_ImportFD,
31    your app must shuttle encrypted data between
32    the real network and memio's network buffers.
33    memio_GetReadParams/memio_PutReadResult
34    are the hooks you need to pump data into memio's input buffer,
35    and memio_GetWriteParams/memio_PutWriteResult
36    are the hooks you need to pump data out of memio's output buffer.
37----------------------------------------------------------------------*/
38
39/* Create the I/O layer and its two circular buffers. */
40PRFileDesc *memio_CreateIOLayer(int readbufsize, int writebufsize);
41
42/* Must call before trying to make an ssl connection */
43void memio_SetPeerName(PRFileDesc *fd, const PRNetAddr *peername);
44
45/* Return a private pointer needed by the following
46 * four functions.  (We could have passed a PRFileDesc to
47 * them, but that would be slower.  Better for the caller
48 * to grab the pointer once and cache it.
49 * This may be a premature optimization.)
50 */
51memio_Private *memio_GetSecret(PRFileDesc *fd);
52
53/* Ask memio how many bytes were requested by a higher layer if the
54 * last attempt to read data resulted in PR_WOULD_BLOCK_ERROR, due to the
55 * transport buffer being empty. If the last attempt to read data from the
56 * memio did not result in PR_WOULD_BLOCK_ERROR, returns 0.
57 */
58int memio_GetReadRequest(memio_Private *secret);
59
60/* Ask memio where to put bytes from the network, and how many it can handle.
61 * Returns bytes available to write, or 0 if none available.
62 * Puts current buffer position into *buf.
63 */
64int memio_GetReadParams(memio_Private *secret, char **buf);
65
66/* Ask memio how many bytes are contained in the internal buffer.
67 * Returns bytes available to read, or 0 if none available.
68 */
69int memio_GetReadableBufferSize(memio_Private *secret);
70
71/* Tell memio how many bytes were read from the network.
72 * If bytes_read is 0, causes EOF to be reported to
73 * NSS after it reads the last byte from the circular buffer.
74 * If bytes_read is < 0, it is treated as an NSPR error code.
75 * See nspr/pr/src/md/unix/unix_errors.c for how to
76 * map from Unix errors to NSPR error codes.
77 * On EWOULDBLOCK or the equivalent, don't call this function.
78 */
79void memio_PutReadResult(memio_Private *secret, int bytes_read);
80
81/* Ask memio what data it has to send to the network.
82 * If there was previous a write error, the NSPR error code is returned.
83 * Otherwise, it returns 0 and provides up to two buffers of data by
84 * writing the positions and lengths into |buf1|, |len1| and |buf2|, |len2|.
85 */
86int memio_GetWriteParams(memio_Private *secret,
87                         const char **buf1, unsigned int *len1,
88                         const char **buf2, unsigned int *len2);
89
90/* Tell memio how many bytes were sent to the network.
91 * If bytes_written is < 0, it is treated as an NSPR error code.
92 * See nspr/pr/src/md/unix/unix_errors.c for how to
93 * map from Unix errors to NSPR error codes.
94 * On EWOULDBLOCK or the equivalent, don't call this function.
95 */
96void memio_PutWriteResult(memio_Private *secret, int bytes_written);
97
98#ifdef __cplusplus
99}
100#endif
101
102#endif
103