| @@ -201,14 +201,21 @@ pub fn to_u16s<S: AsRef>(s: S) -> crate::io::Result<Vec> { |
|
|
| 201 |
201 |
// currently reside in the buffer. This function is an abstraction over these |
| 202 |
202 |
// functions by making them easier to call. |
| 203 |
203 |
// |
| 204 |
|
-// The first callback, `f1`, is yielded a (pointer, len) pair which can be |
|
204 |
+// The first callback, `f1`, is passed a (pointer, len) pair which can be |
| 205 |
205 |
// passed to a syscall. The `ptr` is valid for `len` items (u16 in this case). |
| 206 |
|
-// The closure is expected to return what the syscall returns which will be |
| 207 |
|
-// interpreted by this function to determine if the syscall needs to be invoked |
| 208 |
|
-// again (with more buffer space). |
|
206 |
+// The closure is expected to: |
|
207 |
+// - On success, return the actual length of the written data *without* the null terminator. |
|
208 |
+// This can be 0. In this case the last_error must be left unchanged. |
|
209 |
+// - On insufficient buffer space, |
|
210 |
+// - either return the required length *with* the null terminator, |
|
211 |
+// - or set the last-error to ERROR_INSUFFICIENT_BUFFER and return `len`. |
|
212 |
+// - On other failure, return 0 and set last_error. |
|
213 |
+// |
|
214 |
+// This is how most but not all syscalls indicate the required buffer space. |
|
215 |
+// Other syscalls may need translation to match this protocol. |
| 209 |
216 |
// |
| 210 |
217 |
// Once the syscall has completed (errors bail out early) the second closure is |
| 211 |
|
-// yielded the data which has been read from the syscall. The return value |
|
218 |
+// passed the data which has been read from the syscall. The return value |
| 212 |
219 |
// from this closure is then the return value of the function. |
| 213 |
220 |
pub fn fill_utf16_buf<F1, F2, T>(mut f1: F1, f2: F2) -> crate::io::Result<T> |
| 214 |
221 |
where |