Preliminary support for opening data-transfer interfaces
[people/sha0/gpxe.git] / src / include / gpxe / xfer.h
1 #ifndef _GPXE_XFER_H
2 #define _GPXE_XFER_H
3
4 /** @file
5  *
6  * Data transfer interfaces
7  *
8  */
9
10 #include <stddef.h>
11 #include <stdarg.h>
12 #include <gpxe/interface.h>
13 #include <gpxe/iobuf.h>
14
15 struct xfer_interface;
16
17 /** Data transfer interface operations */
18 struct xfer_interface_operations {
19
20         /* Missing features:
21          *
22          * notification of non-close status - e.g. connected/opened, ...
23          *
24          * seek
25          *
26          * prompt for data delivery
27          *
28          * I/O buffer preparation
29          *
30          */
31
32
33         /** Close interface
34          *
35          * @v xfer              Data-transfer interface
36          * @v rc                Reason for close
37          */
38         void ( * close ) ( struct xfer_interface *xfer, int rc );
39         /** Redirect to new location
40          *
41          * @v xfer              Data-transfer interface
42          * @v type              New location type
43          * @v args              Remaining arguments depend upon location type
44          * @ret rc              Return status code
45          */
46         int ( * vredirect ) ( struct xfer_interface *xfer, int type,
47                               va_list args );
48         /** Deliver datagram
49          *
50          * @v xfer              Data-transfer interface
51          * @v iobuf             Datagram I/O buffer
52          * @ret rc              Return status code
53          *
54          * A data transfer interface that wishes to support only raw
55          * data delivery should set this method to
56          * deliver_as_raw().
57          */
58         int ( * deliver ) ( struct xfer_interface *xfer,
59                             struct io_buffer *iobuf );
60         /** Deliver datagram as raw data
61          *
62          * @v xfer              Data-transfer interface
63          * @v data              Data buffer
64          * @v len               Length of data buffer
65          * @ret rc              Return status code
66          *
67          * A data transfer interface that wishes to support only I/O
68          * buffer delivery should set this method to
69          * deliver_as_iobuf().
70          */
71         int ( * deliver_raw ) ( struct xfer_interface *xfer,
72                                 const void *data, size_t len );
73 };
74
75 /** A data transfer interface */
76 struct xfer_interface {
77         /** Generic object communication interface */
78         struct interface intf;
79         /** Operations for received messages */
80         struct xfer_interface_operations *op;
81 };
82
83 extern struct xfer_interface null_xfer;
84 extern struct xfer_interface_operations null_xfer_ops;
85
86 extern int vredirect ( struct xfer_interface *xfer, int type, va_list args );
87 extern int redirect ( struct xfer_interface *xfer, int type, ... );
88 extern int deliver ( struct xfer_interface *xfer, struct io_buffer *iobuf );
89 extern int deliver_raw ( struct xfer_interface *xfer,
90                          const void *data, size_t len );
91
92 extern int deliver_as_raw ( struct xfer_interface *xfer,
93                             struct io_buffer *iobuf );
94 extern int deliver_as_iobuf ( struct xfer_interface *xfer,
95                               const void *data, size_t len );
96
97 /**
98  * Get destination data-transfer interface
99  *
100  * @v xfer              Data-transfer interface
101  * @ret dest            Destination interface
102  */
103 static inline struct xfer_interface *
104 xfer_dest ( struct xfer_interface *xfer ) {
105         return container_of ( xfer->intf.dest, struct xfer_interface, intf );
106 }
107
108 /**
109  * Plug a data-transfer interface into a new destination interface
110  *
111  * @v xfer              Data-transfer interface
112  * @v dest              New destination interface
113  */
114 static inline void xfer_plug ( struct xfer_interface *xfer,
115                                struct xfer_interface *dest ) {
116         plug ( &xfer->intf, &dest->intf );
117 }
118
119 /**
120  * Unplug a data-transfer interface
121  *
122  * @v xfer              Data-transfer interface
123  */
124 static inline void xfer_unplug ( struct xfer_interface *xfer ) {
125         plug ( &xfer->intf, &null_xfer.intf );
126 }
127
128 /**
129  * Terminate a data-transfer interface
130  *
131  * @v xfer              Data-transfer interface
132  *
133  * After calling this method, no further messages will be received via
134  * the interface.
135  */
136 static inline void xfer_terminate ( struct xfer_interface *xfer ) {
137         xfer->op = &null_xfer_ops;
138 };
139
140 #endif /* _GPXE_XFER_H */