Added PXENV_GET_FILE_SIZE.
[people/xl0/gpxe-arm.git] / src / doc / pxe_extensions
1 FILE OPEN
2
3 Op-Code:        PXENV_FILE_OPEN (00e0h)
4
5 Input:          Far pointer to a t_PXENV_FILE_OPEN parameter structure
6                 that has been initialised by the caller.
7
8 Output:         PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
9                 returned in AX.  The status field in the parameter
10                 structure must be set to one of the values represented
11                 by the PXENV_STATUS_xxx constants.
12
13 Description:    Opens a file specified by a URL for reading.  Multiple
14                 files may be opened and used concurrently.
15
16
17 typedef struct s_PXENV_FILE_OPEN {
18         PXENV_STATUS Status;
19         UINT16 FileHandle;
20         SEGOFF16 FileName;
21         UINT32 Reserved;
22 } t_PXENV_FILE_OPEN;
23
24
25 Set before calling API service:
26
27 FileName:       URL of file to be opened.  Null terminated.
28
29 Reserved:       Must be zero.
30
31
32 Returned from API service:
33
34 FileHandle:     Handle for use in subsequent PXE FILE API calls.
35
36 Status:         See PXENV_STATUS_xxx constants.
37
38
39
40
41 FILE CLOSE
42
43 Op-Code:        PXENV_FILE_CLOSE (00e1h)
44
45 Input:          Far pointer to a t_PXENV_FILE_CLOSE parameter structure
46                 that has been initialised by the caller.
47
48 Output:         PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
49                 returned in AX.  The status field in the parameter
50                 structure must be set to one of the values represented
51                 by the PXENV_STATUS_xxx constants.
52
53 Description:    Closes a previously opened file.
54
55
56 typedef struct s_PXENV_FILE_CLOSE {
57         PXENV_STATUS Status;
58         UINT16 FileHandle;
59 } t_PXENV_FILE_CLOSE;
60
61
62 Set before calling API service:
63
64 FileHandle:     Handle obtained when file was opened.
65
66
67 Returned from API service:
68
69 Status:         See PXENV_STATUS_xxx constants.
70
71
72
73
74 FILE SELECT
75
76 Op-Code:        PXENV_FILE_SELECT (00e2h)
77
78 Input:          Far pointer to a t_PXENV_FILE_SELECT parameter structure
79                 that has been initialised by the caller.
80
81 Output:         PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
82                 returned in AX.  The status field in the parameter
83                 structure must be set to one of the values represented
84                 by the PXENV_STATUS_xxx constants.
85
86 Description:    Check a previously opened file's readiness for I/O.
87
88
89 typedef struct s_PXENV_FILE_SELECT {
90         PXENV_STATUS Status;
91         UINT16 FileHandle;
92         UINT16 Ready;
93 #define RDY_READ 0x0001
94 } t_PXENV_FILE_SELECT;
95
96
97 Set before calling API service:
98
99 FileHandle:     Handle obtained when file was opened.
100
101
102 Returned from API service:
103
104 Ready:          Indication of readiness.  This can be zero, or more,
105                 of the RDY_xxx constants.  Multiple values are
106                 arithmetically or-ed together.
107
108 Status:         See PXENV_STATUS_xxx constants.
109
110
111
112
113 FILE READ
114
115 Op-Code:        PXENV_FILE_READ (00e3h)
116
117 Input:          Far pointer to a t_PXENV_FILE_READ parameter structure
118                 that has been initialised by the caller.
119
120 Output:         PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
121                 returned in AX.  The status field in the parameter
122                 structure must be set to one of the values represented
123                 by the PXENV_STATUS_xxx constants.
124
125                 This API function is non-blocking.  PXENV_EXIT_SUCCESS
126                 and PXENV_STATUS_SUCCESS is returned if a data block
127                 has been transferred into the caller's buffer.
128                 PXENV_EXIT_FAILURE and PXENV_STATUS_FAILURE is
129                 returned if no data is available to transfer.
130
131 Description:    Read from a previously opened file.
132
133
134 typedef struct s_PXENV_FILE_READ {
135         PXENV_STATUS Status;
136         UINT16 FileHandle;
137         UINT16 BufferSize;
138         SEGOFF16 Buffer;
139 } t_PXENV_FILE_READ;
140
141
142 Set before calling API service:
143
144 FileHandle:     Handle obtained when file was opened.
145
146 BufferSize:     Maximum number of data bytes that can be copied into
147                 Buffer.
148
149 Buffer:         Segment:Offset address of data buffer.
150
151
152 Returned from API service:
153
154 BufferSize:     Number of bytes written to the data buffer.  End of
155                 file if this is zero.
156
157 Status:         See PXENV_STATUS_xxx constants.
158
159
160
161
162 GET FILE SIZE
163
164 Op-Code:        PXENV_GET_FILE_SIZE (00e4h)
165
166 Input:          Far pointer to a t_PXENV_GET_FILE_SIZE parameter
167                 structure that has been initialised by the caller.
168
169 Output:         PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be
170                 returned in AX.  The status field in the parameter
171                 structure must be set to one of the values represented
172                 by the PXENV_STATUS_xxx constants.
173
174 Description:    Determine size of a previously opened file.
175
176
177 typedef struct s_PXENV_GET_FILE_SIZE {
178         PXENV_STATUS Status;
179         UINT16 FileHandle;
180         UINT32 FileSize;
181 } t_PXENV_GET_FILE_SIZE;
182
183
184 Set before calling API service:
185
186 FileHandle:     Handle obtained when file was opened.
187
188
189 Returned from API service:
190
191 FileSize:       Size of the file in bytes.
192
193 Status:         See PXENV_STATUS_xxx constants.