1 /* This Source Code Form is subject to the terms of the Mozilla Public
2  * License, v. 2.0. If a copy of the MPL was not distributed with this
3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4 /*
5  * pkix_pl_socket.h
6  *
7  * Socket Object Type Definition
8  *
9  */
10 
11 #ifndef _PKIX_PL_SOCKET_H
12 #define _PKIX_PL_SOCKET_H
13 
14 #include <errno.h>
15 #include "pkix_pl_common.h"
16 
17 #ifdef __cplusplus
18 extern "C" {
19 #endif
20 
21 typedef enum {
22         SOCKET_BOUND,
23         SOCKET_LISTENING,
24         SOCKET_ACCEPTPENDING,
25         SOCKET_UNCONNECTED,
26         SOCKET_CONNECTPENDING,
27         SOCKET_CONNECTED,
28         SOCKET_SENDPENDING,
29         SOCKET_RCVPENDING,
30         SOCKET_SENDRCVPENDING,
31         SOCKET_SHUTDOWN
32 } SockStatus;
33 
34 /* This is the default port number, if none is supplied to CreateByName. */
35 #define LDAP_PORT 389
36 
37 /*
38  * These callbacks allow a user to substitute a counterfeit socket in places
39  * where a PKIX_PL_Socket is expected. A conforming usage will use the
40  * ListenCallback function instead of Listen, AcceptCallback instead of Accept,
41  * etc. The counterfeit socket may have special capabilites such as the
42  * ability to do proxy authentication, etc.
43  */
44 
45 typedef PKIX_Error *
46 (*pkix_pl_Socket_ListenCallback)(
47         PKIX_PL_Socket *socket,
48         PKIX_UInt32 backlog,
49         void *plContext);
50 
51 typedef PKIX_Error *
52 (*pkix_pl_Socket_AcceptCallback)(
53         PKIX_PL_Socket *socket,
54         PKIX_PL_Socket **pRendezvousSock,
55         void *plContext);
56 
57 typedef PKIX_Error *
58 (*pkix_pl_Socket_ConnectContinueCallback)(
59         PKIX_PL_Socket *socket,
60         PRErrorCode *pStatus,
61         void *plContext);
62 
63 typedef PKIX_Error *
64 (*pkix_pl_Socket_SendCallback)(
65         PKIX_PL_Socket *sendSock,
66         void *buf,
67         PKIX_UInt32 bytesToWrite,
68         PKIX_Int32 *pBytesWritten,
69         void *plContext);
70 
71 typedef PKIX_Error *
72 (*pkix_pl_Socket_RecvCallback)(
73         PKIX_PL_Socket *rcvSock,
74         void *buf,
75         PKIX_UInt32 capacity,
76         PKIX_Int32 *pBytesRead,
77         void *plContext);
78 
79 typedef PKIX_Error *
80 (*pkix_pl_Socket_PollCallback)(
81         PKIX_PL_Socket *sock,
82         PKIX_Int32 *pBytesWritten,
83         PKIX_Int32 *pBytesRead,
84         void *plContext);
85 
86 typedef PKIX_Error *
87 (*pkix_pl_Socket_ShutdownCallback)(
88         PKIX_PL_Socket *socket, void *plContext);
89 
90 typedef struct PKIX_PL_Socket_CallbackStruct {
91         pkix_pl_Socket_ListenCallback listenCallback;
92         pkix_pl_Socket_AcceptCallback acceptCallback;
93         pkix_pl_Socket_ConnectContinueCallback connectcontinueCallback;
94         pkix_pl_Socket_SendCallback sendCallback;
95         pkix_pl_Socket_RecvCallback recvCallback;
96         pkix_pl_Socket_PollCallback pollCallback;
97         pkix_pl_Socket_ShutdownCallback shutdownCallback;
98 } PKIX_PL_Socket_Callback;
99 
100 struct PKIX_PL_SocketStruct {
101         PKIX_Boolean isServer;
102         PRIntervalTime timeout; /* zero for non-blocking I/O */
103         SockStatus status;
104         PRFileDesc *clientSock;
105         PRFileDesc *serverSock;
106         void *readBuf;
107         void *writeBuf;
108         PKIX_UInt32 readBufSize;
109         PKIX_UInt32 writeBufSize;
110         PRNetAddr *netAddr;
111         PKIX_PL_Socket_Callback callbackList;
112 };
113 
114 /* see source file for function documentation */
115 
116 PKIX_Error *pkix_pl_Socket_RegisterSelf(void *plContext);
117 
118 PKIX_Error *
119 pkix_pl_Socket_Create(
120         PKIX_Boolean isServer,
121         PRIntervalTime timeout, /* zero for non-blocking I/O */
122         PRNetAddr *netAddr,
123         PRErrorCode *status,
124         PKIX_PL_Socket **pSocket,
125         void *plContext);
126 
127 PKIX_Error *
128 pkix_pl_Socket_CreateByName(
129         PKIX_Boolean isServer,
130         PRIntervalTime timeout,
131         char *serverName,
132         PRErrorCode *pStatus,
133         PKIX_PL_Socket **pSocket,
134         void *plContext);
135 
136 PKIX_Error *
137 pkix_pl_Socket_CreateByHostAndPort(
138         PKIX_Boolean isServer,
139         PRIntervalTime timeout,
140         char *hostname,
141         PRUint16 portnum,
142         PRErrorCode *pStatus,
143         PKIX_PL_Socket **pSocket,
144         void *plContext);
145 
146 /* Do not use these functions directly; use their callback variants instead
147  *      static PKIX_Error *
148  *      pkix_pl_Socket_Listen(
149  *              PKIX_PL_Socket *socket,
150  *              PKIX_UInt32 backlog,
151  *              void *plContext);
152  *
153  *      static PKIX_Error *
154  *      pkix_pl_Socket_Accept(
155  *              PKIX_PL_Socket *socket,
156  *              PKIX_PL_Socket **pRendezvousSock,
157  *              void *plContext);
158  *
159  *      static PKIX_Error *
160  *      pkix_pl_Socket_ConnectContinue(
161  *              PKIX_PL_Socket *socket,
162  *              PRErrorCode *pStatus,
163  *              void *plContext);
164  *
165  *      static PKIX_Error *
166  *      pkix_pl_Socket_Send(
167  *              PKIX_PL_Socket *sendSock,
168  *              void *buf,
169  *              PKIX_UInt32 bytesToWrite,
170  *              PKIX_Int32 *pBytesWritten,
171  *              void *plContext);
172  *
173  *      static PKIX_Error *
174  *      pkix_pl_Socket_Recv(
175  *              PKIX_PL_Socket *rcvSock,
176  *              void *buf,
177  *              PKIX_UInt32 capacity,
178  *              PKIX_Int32 *pBytesRead,
179  *              void *plContext);
180  *
181  *      static PKIX_Error *
182  *      pkix_pl_Socket_Poll(
183  *              PKIX_PL_Socket *sock,
184  *              PKIX_Int32 *pBytesWritten,
185  *              PKIX_Int32 *pBytesRead,
186  *              void *plContext);
187  *
188  *      static PKIX_Error *
189  *      pkix_pl_Socket_Shutdown(
190  *              PKIX_PL_Socket *socket, void *plContext);
191  */
192 
193 PKIX_Error *
194 pkix_pl_Socket_GetCallbackList(
195         PKIX_PL_Socket *socket,
196         PKIX_PL_Socket_Callback **pCallbackList,
197         void *plContext);
198 
199 PKIX_Error *
200 pkix_pl_Socket_GetPRFileDesc(
201         PKIX_PL_Socket *socket,
202         PRFileDesc **pDesc,
203         void *plContext);
204 
205 #ifdef __cplusplus
206 }
207 #endif
208 
209 #endif /* _PKIX_PL_SOCKET_H */
210