[mswsock] TransmitFile should work now [3/4] - documentation

[Łukasz Chróst]

Changelog:
    - updated documentation for TransmitFile

--
Łukasz Chróst
-------------- next part --------------
Index: dlls/mswsock/mswsock.c
===================================================================
RCS file: /home/wine/wine/dlls/mswsock/mswsock.c,v
retrieving revision 1.4
diff -u -r1.4 mswsock.c
--- dlls/mswsock/mswsock.c	23 May 2006 12:48:20 -0000	1.4
+++ dlls/mswsock/mswsock.c	29 Jun 2006 13:15:58 -0000
@@ -93,27 +93,51 @@
 /***********************************************************************
  *		TransmitFile (MSWSOCK.@)
  *
- * This function is used to transmit a file over socket.
+ * Transmit file via socket. Header  / Footer data is also supported.
  *
- * TODO
- *  This function is currently implemented as a stub.
+ * PARAMS
+ *  hSocket [I]    
+ *      Socket for sending the data. Not handle. This has to be (possibly
+ *      connected) stream socket.
+ *  hFile  [I]  (optional)
+ *      Handle to open file to transmit data from. Optional - if null just 
+ *      the header/tail data is sent.
+ *  nNumberOfBytesToWrite [I] (optional)
+ *      How much data to write to socket. The function extis when sent this
+ *      amount of data or when there is no data left to send.
+ *  nNumberOfBytesPerSend  [I] (optional)
+ *      Maximum length of single packet (usefull for communication protocols)
+ *      Note the length is also system limited and connection specific.
+ *  lpOverlapped [I/O] (optional)
+ *      Structure used for overlapped operations. Use lpOverlapped->Offset
+ *      to send file data from given position (counting from file beggining). 
+ *  lpTransmitBuffers [I] (optional)
+ *      data to send as head/tail, usefull for some communication protocols
+ *  dwFlags [I] 
+ *      communication flags. (only TF_DISCONNECT has real meaning at this time).
+ *
+ * RETURNS
+ *  Success: 
+ *      For non-overlapped operation: TRUE, 
+ *      For overlapped operation : TRUE or FALSE with WSA_IO_PENDING error code 
+ *      set.To get actual result in overlapped mode call WSAGetOverlappedResult.
+ *  Failure: 
+ *      FALSE, Use WSAGetLastError to get reason.
+ *
+ * NOTES
+ *  The function is most often used to transmit file data, without need of coding
+ *  'while(read) send' loop.
+ *
+ * BUGS
+ *      lpOverlapped->OffsetHigh  is not supported.
+ *      limited to ULONG files size (see above)
+ *      doesn't support TF_REUSE_SOCKET
+ *      doesn't support async IO. Note: some of it is simulated via lpOverlapped.
  */
 
-BOOL WINAPI TransmitFile(
-        SOCKET hSocket, /* [in] Handle to a connected socket */
-	HANDLE hFile,   /* [in] Handle to the open file that should be
-                           transmited */
-	DWORD nNumberOfBytesToWrite, /* [in] Number of file bytes to 
-                                        transmit */
-	DWORD nNumberOfBytesPerSend, /* [in] Size in bytes of each block of
-                                         data sent in each send operation */
-	LPOVERLAPPED lpOverlapped, /* [in] Specify in order to achieve an 
-                                      overlapped (asynchronous) I/O 
-                                      operation */
-	LPTRANSMIT_FILE_BUFFERS lpTransmitBuffers, 
-		/* [in] Contains pointers to data to send before and after
-                   the file data is sent */
-	DWORD dwFlags) /* [in] Flags */
+BOOL WINAPI TransmitFile(SOCKET hSocket, HANDLE hFile, DWORD nNumberOfBytesToWrite,
+  	DWORD nNumberOfBytesPerSend, LPOVERLAPPED lpOverlapped, 
+    LPTRANSMIT_FILE_BUFFERS lpTransmitBuffers, 	DWORD dwFlags)
 {
     FIXME("not implemented\n");