iphlpapi: doc update
Markus Amsler
markus.amsler at oribi.org
Sun Nov 13 08:05:33 CST 2005
Changelog:
Markus Amsler <markus.amsler at oribi.org>
Add, reformat API documentation.
-------------- next part --------------
Index: dlls/iphlpapi/iphlpapi_main.c
===================================================================
RCS file: /home/wine/wine/dlls/iphlpapi/iphlpapi_main.c,v
retrieving revision 1.20
diff -u -r1.20 iphlpapi_main.c
--- dlls/iphlpapi/iphlpapi_main.c 12 Sep 2005 10:30:06 -0000 1.20
+++ dlls/iphlpapi/iphlpapi_main.c 13 Nov 2005 14:00:34 -0000
@@ -68,20 +68,21 @@
/******************************************************************
* AddIPAddress (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Add an IP address to an adapter.
*
* PARAMS
- *
- * Address [In]
- * IpMask [In]
- * IfIndex [In]
- * NTEContext [In/Out]
- * NTEInstance [In/Out]
+ * Address [In] IP address to add to the adapter
+ * IpMask [In] subnet mask for the IP address
+ * IfIndex [In] adapter index to add the address
+ * NTEContext [Out] Net Table Entry (NTE) context for the IP address
+ * NTEInstance [Out] NTE instance for the IP address
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub. Currently returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI AddIPAddress(IPAddr Address, IPMask IpMask, DWORD IfIndex, PULONG NTEContext, PULONG NTEInstance)
{
@@ -94,20 +95,19 @@
/******************************************************************
* AllocateAndGetIfTableFromStack (IPHLPAPI.@)
*
- * NOTES
- * Like GetIfTable, but allocates the returned table from heap.
+ * Get table of local interfaces.
+ * Like GetIfTable(), but allocate the returned table from heap.
*
* PARAMS
+ * ppIfTable [Out] pointer into which the MIB_IFTABLE is
+ * allocated and returned.
+ * bOrder [In] passed to GetIfTable() to order the table
+ * heap [In] heap from which the table is allocated
+ * flags [In] flags to HeapAlloc
*
- * ppIfTable [Out] -- pointer into which the MIB_IFTABLE is
- * allocated and returned.
- * bOrder [In] -- passed to GetIfTable to order the table
- * heap [In] -- heap from which the table is allocated
- * flags [In] -- flags to HeapAlloc
- *
- * RETURNS -- ERROR_INVALID_PARAMETER if ppIfTable is NULL, whatever
- * GetIfTable returns otherwise
- *
+ * RETURNS
+ * ERROR_INVALID_PARAMETER if ppIfTable is NULL, whatever
+ * GetIfTable() returns otherwise.
*/
DWORD WINAPI AllocateAndGetIfTableFromStack(PMIB_IFTABLE *ppIfTable,
BOOL bOrder, HANDLE heap, DWORD flags)
@@ -135,20 +135,19 @@
/******************************************************************
* AllocateAndGetIpAddrTableFromStack (IPHLPAPI.@)
*
- * NOTES
- * Like GetIpAddrTable, but allocates the returned table from heap.
+ * Get interface-to-IP address mapping table.
+ * Like GetIpAddrTable(), but allocate the returned table from heap.
*
* PARAMS
- *
- * ppIpAddrTable [Out]
- * bOrder [In] -- passed to GetIpAddrTable to order the table
- * heap [In] -- heap from which the table is allocated
- * flags [In] -- flags to HeapAlloc
+ * ppIpAddrTable [Out] pointer into which the MIB_IPADDRTABLE is
+ * allocated and returned.
+ * bOrder [In] passed to GetIpAddrTable to order the table
+ * heap [In] heap from which the table is allocated
+ * flags [In] flags to HeapAlloc
*
* RETURNS
- * ERROR_INVALID_PARAMETER if ppIpAddrTable is NULL, whatever GetIpAddrTable
- * returns otherwise.
- *
+ * ERROR_INVALID_PARAMETER if ppIpAddrTable is NULL, whatever GetIpAddrTable()
+ * returns otherwise.
*/
DWORD WINAPI AllocateAndGetIpAddrTableFromStack(PMIB_IPADDRTABLE *ppIpAddrTable,
BOOL bOrder, HANDLE heap, DWORD flags)
@@ -176,20 +175,19 @@
/******************************************************************
* AllocateAndGetIpForwardTableFromStack (IPHLPAPI.@)
*
- * NOTES
- * Like GetIpForwardTable, but allocates the returned table from heap.
+ * Get the route table.
+ * Like GetIpForwardTable(), but allocate the returned table from heap.
*
* PARAMS
+ * ppIpForwardTable [Out] pointer into which the MIB_IPFORWARDTABLE is
+ * allocated and returned.
+ * bOrder [In] passed to GetIfTable to order the table
+ * heap [In] heap from which the table is allocated
+ * flags [In] flags to HeapAlloc
*
- * ppIpForwardTable [Out] -- pointer into which the MIB_IPFORWARDTABLE is
- * allocated and returned.
- * bOrder [In] -- passed to GetIfTable to order the table
- * heap [In] -- heap from which the table is allocated
- * flags [In] -- flags to HeapAlloc
- *
- * RETURNS -- ERROR_INVALID_PARAMETER if ppIfTable is NULL, whatever
- * GetIpForwardTable returns otherwise
- *
+ * RETURNS
+ * ERROR_INVALID_PARAMETER if ppIfTable is NULL, whatever
+ * GetIpForwardTable() returns otherwise.
*/
DWORD WINAPI AllocateAndGetIpForwardTableFromStack(PMIB_IPFORWARDTABLE *
ppIpForwardTable, BOOL bOrder, HANDLE heap, DWORD flags)
@@ -217,20 +215,19 @@
/******************************************************************
* AllocateAndGetIpNetTableFromStack (IPHLPAPI.@)
*
- * NOTES
- * Like GetIpNetTable, but allocates the returned table from heap.
+ * Get the IP-to-physical address mapping table.
+ * Like GetIpNetTable(), but allocate the returned table from heap.
*
* PARAMS
- *
- * ppIpNetTable [Out]
- * bOrder [In] -- passed to GetIpNetTable to order the table
- * heap [In] -- heap from which the table is allocated
- * flags [In] -- flags to HeapAlloc
+ * ppIpNetTable [Out] pointer into which the MIB_IPNETTABLE is
+ * allocated and returned.
+ * bOrder [In] passed to GetIpNetTable to order the table
+ * heap [In] heap from which the table is allocated
+ * flags [In] flags to HeapAlloc
*
* RETURNS
- * ERROR_INVALID_PARAMETER if ppIpNetTable is NULL, whatever GetIpNetTable
- * returns otherwise.
- *
+ * ERROR_INVALID_PARAMETER if ppIpNetTable is NULL, whatever GetIpNetTable()
+ * returns otherwise.
*/
DWORD WINAPI AllocateAndGetIpNetTableFromStack(PMIB_IPNETTABLE *ppIpNetTable,
BOOL bOrder, HANDLE heap, DWORD flags)
@@ -258,20 +255,19 @@
/******************************************************************
* AllocateAndGetTcpTableFromStack (IPHLPAPI.@)
*
- * NOTES
- * Like GetTcpTable, but allocates the returned table from heap.
+ * Get the TCP connection table.
+ * Like GetTcpTable(), but allocate the returned table from heap.
*
* PARAMS
- *
- * ppTcpTable [Out]
- * bOrder [In] -- passed to GetTcpTable to order the table
- * heap [In] -- heap from which the table is allocated
- * flags [In] -- flags to HeapAlloc
+ * ppTcpTable [Out] pointer into which the MIB_TCPTABLE is
+ * allocated and returned.
+ * bOrder [In] passed to GetTcpTable to order the table
+ * heap [In] heap from which the table is allocated
+ * flags [In] flags to HeapAlloc
*
* RETURNS
- * ERROR_INVALID_PARAMETER if ppTcpTable is NULL, whatever GetTcpTable
- * returns otherwise.
- *
+ * ERROR_INVALID_PARAMETER if ppTcpTable is NULL, whatever GetTcpTable()
+ * returns otherwise.
*/
DWORD WINAPI AllocateAndGetTcpTableFromStack(PMIB_TCPTABLE *ppTcpTable,
BOOL bOrder, HANDLE heap, DWORD flags)
@@ -299,20 +295,19 @@
/******************************************************************
* AllocateAndGetUdpTableFromStack (IPHLPAPI.@)
*
- * NOTES
- * Like GetUdpTable, but allocates the returned table from heap.
+ * Get the UDP listener table.
+ * Like GetUdpTable(), but allocate the returned table from heap.
*
* PARAMS
- *
- * ppUdpTable [Out]
- * bOrder [In] -- passed to GetUdpTable to order the table
- * heap [In] -- heap from which the table is allocated
- * flags [In] -- flags to HeapAlloc
+ * ppUdpTable [Out] pointer into which the MIB_UDPTABLE is
+ * allocated and returned.
+ * bOrder [In] passed to GetUdpTable to order the table
+ * heap [In] heap from which the table is allocated
+ * flags [In] flags to HeapAlloc
*
* RETURNS
- * ERROR_INVALID_PARAMETER if ppUdpTable is NULL, whatever GetUdpTable
- * returns otherwise.
- *
+ * ERROR_INVALID_PARAMETER if ppUdpTable is NULL, whatever GetUdpTable()
+ * returns otherwise.
*/
DWORD WINAPI AllocateAndGetUdpTableFromStack(PMIB_UDPTABLE *ppUdpTable,
BOOL bOrder, HANDLE heap, DWORD flags)
@@ -340,16 +335,17 @@
/******************************************************************
* CreateIpForwardEntry (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Create a route in the local computer's IP table.
*
* PARAMS
- *
- * pRoute [In/Out]
+ * pRoute [In] new route information
*
* RETURNS
- * 0
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns allways NO_ERROR.
*/
DWORD WINAPI CreateIpForwardEntry(PMIB_IPFORWARDROW pRoute)
{
@@ -362,16 +358,17 @@
/******************************************************************
* CreateIpNetEntry (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Create entry in the ARP table.
*
* PARAMS
- *
- * pArpEntry [In/Out]
+ * pArpEntry [In] new ARP entry
*
* RETURNS
- * 0
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns allways NO_ERROR.
*/
DWORD WINAPI CreateIpNetEntry(PMIB_IPNETROW pArpEntry)
{
@@ -384,18 +381,19 @@
/******************************************************************
* CreateProxyArpEntry (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Create a Proxy ARP (PARP) entry for an IP address.
*
* PARAMS
- *
- * dwAddress [In]
- * dwMask [In]
- * dwIfIndex [In]
+ * dwAddress [In] IP address for which this computer acts as a proxy.
+ * dwMask [In] subnet mask for dwAddress
+ * dwIfIndex [In] interface index
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI CreateProxyArpEntry(DWORD dwAddress, DWORD dwMask, DWORD dwIfIndex)
{
@@ -409,16 +407,17 @@
/******************************************************************
* DeleteIPAddress (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Delete an IP address added with AddIPAddress().
*
* PARAMS
- *
- * NTEContext [In]
+ * NTEContext [In] NTE context from AddIPAddress();
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI DeleteIPAddress(ULONG NTEContext)
{
@@ -431,16 +430,17 @@
/******************************************************************
* DeleteIpForwardEntry (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Delete a route.
*
* PARAMS
- *
- * pRoute [In/Out]
+ * pRoute [In] route to delete
*
* RETURNS
- * 0
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns NO_ERROR.
*/
DWORD WINAPI DeleteIpForwardEntry(PMIB_IPFORWARDROW pRoute)
{
@@ -453,16 +453,17 @@
/******************************************************************
* DeleteIpNetEntry (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Delete an ARP entry.
*
* PARAMS
- *
- * pArpEntry [In/Out]
+ * pArpEntry [In] ARP entry to delete
*
* RETURNS
- * 0
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns NO_ERROR.
*/
DWORD WINAPI DeleteIpNetEntry(PMIB_IPNETROW pArpEntry)
{
@@ -475,18 +476,19 @@
/******************************************************************
* DeleteProxyArpEntry (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Delete a Proxy ARP entry.
*
* PARAMS
- *
- * dwAddress [In]
- * dwMask [In]
- * dwIfIndex [In]
+ * dwAddress [In] IP address for which this computer acts as a proxy.
+ * dwMask [In] subnet mask for dwAddress
+ * dwIfIndex [In] interface index
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI DeleteProxyArpEntry(DWORD dwAddress, DWORD dwMask, DWORD dwIfIndex)
{
@@ -500,17 +502,18 @@
/******************************************************************
* EnableRouter (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Turn on ip forwarding.
*
* PARAMS
- *
- * pHandle [In/Out]
- * pOverlapped [In/Out]
+ * pHandle [In/Out]
+ * pOverlapped [In/Out] hEvent member should contain a valid handle.
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: ERROR_IO_PENDING
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI EnableRouter(HANDLE * pHandle, OVERLAPPED * pOverlapped)
{
@@ -525,16 +528,17 @@
/******************************************************************
* FlushIpNetTable (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Delete all ARP entries of an interface
*
* PARAMS
- *
- * dwIfIndex [In]
+ * dwIfIndex [In] interface index
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI FlushIpNetTable(DWORD dwIfIndex)
{
@@ -548,17 +552,18 @@
/******************************************************************
* GetAdapterIndex (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Get interface index from its name.
*
* PARAMS
- *
- * AdapterName [In/Out]
- * IfIndex [In/Out]
+ * AdapterName [In] unicode string with the adapter name
+ * IfIndex [Out] returns found interface index
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI GetAdapterIndex(LPWSTR AdapterName, PULONG IfIndex)
{
@@ -571,15 +576,15 @@
/******************************************************************
* GetAdaptersInfo (IPHLPAPI.@)
*
- * PARAMS
+ * Get information about adapters.
*
- * pAdapterInfo [In/Out]
- * pOutBufLen [In/Out]
+ * PARAMS
+ * pAdapterInfo [Out] buffer for adapter infos
+ * pOutBufLen [In] length of output buffer
*
* RETURNS
- *
- * DWORD
- *
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*/
DWORD WINAPI GetAdaptersInfo(PIP_ADAPTER_INFO pAdapterInfo, PULONG pOutBufLen)
{
@@ -688,15 +693,15 @@
/******************************************************************
* GetBestInterface (IPHLPAPI.@)
*
- * PARAMS
+ * Get the interface, with the best route for the given IP address.
*
- * dwDestAddr [In]
- * pdwBestIfIndex [In/Out]
+ * PARAMS
+ * dwDestAddr [In] IP address to search the interface for
+ * pdwBestIfIndex [Out] found best interface
*
* RETURNS
- *
- * DWORD
- *
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*/
DWORD WINAPI GetBestInterface(IPAddr dwDestAddr, PDWORD pdwBestIfIndex)
{
@@ -720,16 +725,16 @@
/******************************************************************
* GetBestRoute (IPHLPAPI.@)
*
- * PARAMS
+ * Get the best route for the given IP address.
*
- * dwDestAddr [In]
- * dwSourceAddr [In]
- * OUT [In]
+ * PARAMS
+ * dwDestAddr [In] IP address to search the best route for
+ * dwSourceAddr [In] optional source IP address
+ * pBestRoute [Out] found best route
*
* RETURNS
- *
- * DWORD
- *
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*/
DWORD WINAPI GetBestRoute(DWORD dwDestAddr, DWORD dwSourceAddr, PMIB_IPFORWARDROW pBestRoute)
{
@@ -773,18 +778,15 @@
/******************************************************************
* GetFriendlyIfIndex (IPHLPAPI.@)
*
- * NOTES
- * Returns a "friendly" version if IfIndex, which is one that doesn't
+ * Get a "friendly" version of IfIndex, which is one that doesn't
* have the top byte set. Doesn't validate whether IfIndex is a valid
* adapter index.
*
* PARAMS
- *
- * IfIndex [In]
+ * IfIndex [In] interface index to get the friendly one for
*
* RETURNS
- * A friendly version of IfIndex.
- *
+ * A friendly version of IfIndex.
*/
DWORD WINAPI GetFriendlyIfIndex(DWORD IfIndex)
{
@@ -799,14 +801,14 @@
/******************************************************************
* GetIcmpStatistics (IPHLPAPI.@)
*
- * PARAMS
+ * Get the ICMP statistics for the local computer.
*
- * pStats [In/Out]
+ * PARAMS
+ * pStats [Out] buffer for ICMP statistics
*
* RETURNS
- *
- * DWORD
- *
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*/
DWORD WINAPI GetIcmpStatistics(PMIB_ICMP pStats)
{
@@ -822,14 +824,15 @@
/******************************************************************
* GetIfEntry (IPHLPAPI.@)
*
- * PARAMS
+ * Get information about an interface.
*
- * pIfRow [In/Out]
+ * PARAMS
+ * pIfRow [In/Out] In: dwIndex of MIB_IFROW selects the interface.
+ * Out: interface information
*
* RETURNS
- *
- * DWORD
- *
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*/
DWORD WINAPI GetIfEntry(PMIB_IFROW pIfRow)
{
@@ -868,22 +871,22 @@
/******************************************************************
* GetIfTable (IPHLPAPI.@)
*
- * NOTES
- * Returns a table of local interfaces, *pdwSize is the size in bytes of
- * pIfTable. If this is less than required, the function will return
- * ERROR_INSUFFICIENT_BUFFER, and *pdwSize will be set to the required byte
- * size.
- * If bOrder is true, the returned table will be sorted by interface index.
+ * Get a table of local interfaces.
*
* PARAMS
- *
- * pIfTable [In/Out]
- * pdwSize [In/Out]
- * bOrder [In]
+ * pIfTable [Out] buffer for local interfaces table
+ * pdwSize [In/Out] length of output buffer
+ * bOrder [In] whether to sort the table
*
* RETURNS
- * NO_ERROR on success, something else on failure.
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * NOTES
+ * If pdwSize is less than required, the function will return
+ * ERROR_INSUFFICIENT_BUFFER, and *pdwSize will be set to the required byte
+ * size.
+ * If bOrder is true, the returned table will be sorted by interface index.
*/
DWORD WINAPI GetIfTable(PMIB_IFTABLE pIfTable, PULONG pdwSize, BOOL bOrder)
{
@@ -939,15 +942,15 @@
/******************************************************************
* GetInterfaceInfo (IPHLPAPI.@)
*
- * PARAMS
+ * Get a list of network interface adapters.
*
- * pIfTable [In/Out]
- * dwOutBufLen [In/Out]
+ * PARAMS
+ * pIfTable [Out] buffer for intertace adapters
+ * dwOutBufLen [Out] if buffer is too small, returns required size
*
* RETURNS
- *
- * DWORD
- *
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*/
DWORD WINAPI GetInterfaceInfo(PIP_INTERFACE_INFO pIfTable, PULONG dwOutBufLen)
{
@@ -1021,23 +1024,23 @@
/******************************************************************
* GetIpAddrTable (IPHLPAPI.@)
*
- * NOTES
- * Returns the route table. On input, *pdwSize is the size in bytes of
- * pIpForwardTable. If this is less than required, the function will return
- * ERROR_INSUFFICIENT_BUFFER, and *pdwSize will be set to the required byte
- * size.
- * If bOrder is true, the returned table will be sorted by the next hop and
- * an assortment of arbitrary parameters.
+ * Get interface-to-IP address mapping table.
*
* PARAMS
- *
- * pIpAddrTable [In/Out]
- * pdwSize [In/Out]
- * bOrder [In]
+ * pIpAddrTable [Out] buffer for mapping table
+ * pdwSize [In/Out] length of output buffer
+ * bOrder [In] whether to sort the table
*
* RETURNS
- * NO_ERROR on success, something else on failure.
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * NOTES
+ * If pdwSize is less than required, the function will return
+ * ERROR_INSUFFICIENT_BUFFER, and *pdwSize will be set to the required byte
+ * size.
+ * If bOrder is true, the returned table will be sorted by the next hop and
+ * an assortment of arbitrary parameters.
*/
DWORD WINAPI GetIpAddrTable(PMIB_IPADDRTABLE pIpAddrTable, PULONG pdwSize, BOOL bOrder)
{
@@ -1132,23 +1135,23 @@
/******************************************************************
* GetIpForwardTable (IPHLPAPI.@)
*
- * NOTES
- * Returns the route table. On input, *pdwSize is the size in bytes of
- * pIpForwardTable. If this is less than required, the function will return
- * ERROR_INSUFFICIENT_BUFFER, and *pdwSize will be set to the required byte
- * size.
- * If bOrder is true, the returned table will be sorted by the next hop and
- * an assortment of arbitrary parameters.
+ * Get the route table.
*
* PARAMS
- *
- * pIpForwardTable [In/Out]
- * pdwSize [In/Out]
- * bOrder [In]
+ * pIpForwardTable [Out] buffer for route table
+ * pdwSize [In/Out] length of output buffer
+ * bOrder [In] whether to sort the table
*
* RETURNS
- * NO_ERROR on success, something else on failure.
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * NOTES
+ * If pdwSize is less than required, the function will return
+ * ERROR_INSUFFICIENT_BUFFER, and *pdwSize will be set to the required byte
+ * size.
+ * If bOrder is true, the returned table will be sorted by the next hop and
+ * an assortment of arbitrary parameters.
*/
DWORD WINAPI GetIpForwardTable(PMIB_IPFORWARDTABLE pIpForwardTable, PULONG pdwSize, BOOL bOrder)
{
@@ -1238,21 +1241,22 @@
/******************************************************************
* GetIpNetTable (IPHLPAPI.@)
*
- * Returns the ARP cache. On input, *pdwSize is the size in bytes of
- * pIpNetTable. If this is less than required, the function will return
- * ERROR_INSUFFICIENT_BUFFER, and *pdwSize will be set to the required byte
- * size.
- * If bOrder is true, the returned table will be sorted by IP address.
+ * Get the IP-to-physical address mapping table.
*
* PARAMS
- *
- * pIpNetTable [In/Out]
- * pdwSize [In/Out]
- * bOrder [In]
+ * pIpNetTable [Out] buffer for mapping table
+ * pdwSize [In/Out] length of output buffer
+ * bOrder [In] whether to sort the table
*
* RETURNS
- * NO_ERROR on success, something else on failure.
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * NOTES
+ * If pdwSize is less than required, the function will return
+ * ERROR_INSUFFICIENT_BUFFER, and *pdwSize will be set to the required byte
+ * size.
+ * If bOrder is true, the returned table will be sorted by IP address.
*/
DWORD WINAPI GetIpNetTable(PMIB_IPNETTABLE pIpNetTable, PULONG pdwSize, BOOL bOrder)
{
@@ -1302,14 +1306,14 @@
/******************************************************************
* GetIpStatistics (IPHLPAPI.@)
*
- * PARAMS
+ * Get the IP statistics for the local computer.
*
- * pStats [In/Out]
+ * PARAMS
+ * pStats [Out] buffer for IP statistics
*
* RETURNS
- *
- * DWORD
- *
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*/
DWORD WINAPI GetIpStatistics(PMIB_IPSTATS pStats)
{
@@ -1325,15 +1329,20 @@
/******************************************************************
* GetNetworkParams (IPHLPAPI.@)
*
- * PARAMS
+ * Get the network parameters for the local computer.
*
- * pFixedInfo [In/Out]
- * pOutBufLen [In/Out]
+ * PARAMS
+ * pFixedInfo [Out] buffer for network parameters
+ * pOutBufLen [In/Out] lenght of output buffer
*
* RETURNS
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
- * DWORD
- *
+ * NOTES
+ * If pOutBufLen is less than required, the function will return
+ * ERROR_INSUFFICIENT_BUFFER, and pOutBufLen will be set to the required byte
+ * size.
*/
DWORD WINAPI GetNetworkParams(PFIXED_INFO pFixedInfo, PULONG pOutBufLen)
{
@@ -1400,16 +1409,13 @@
/******************************************************************
* GetNumberOfInterfaces (IPHLPAPI.@)
*
- * NOTES
- * Returns the number of interfaces in *pdwNumIf.
+ * Get the number of interfaces.
*
* PARAMS
- *
- * pdwNumIf [In/Out]
+ * pdwNumIf [Out] number of interfaces
*
* RETURNS
- * NO_ERROR on success, ERROR_INVALID_PARAMETER if pdwNumIf is NULL.
- *
+ * NO_ERROR on success, ERROR_INVALID_PARAMETER if pdwNumIf is NULL.
*/
DWORD WINAPI GetNumberOfInterfaces(PDWORD pdwNumIf)
{
@@ -1430,17 +1436,19 @@
/******************************************************************
* GetPerAdapterInfo (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Get information about an adapter corresponding to an interface.
*
* PARAMS
- *
- * IfIndex [In]
- * pPerAdapterInfo [In/Out]
- * pOutBufLen [In/Out]
+ * IfIndex [In] interface info
+ * pPerAdapterInfo [Out] buffer for per adapter info
+ * pOutBufLen [In/Out] length of output buffer
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
+ *
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI GetPerAdapterInfo(ULONG IfIndex, PIP_PER_ADAPTER_INFO pPerAdapterInfo, PULONG pOutBufLen)
{
@@ -1454,19 +1462,21 @@
/******************************************************************
* GetRTTAndHopCount (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Get round-trip time (RTT) and hop count.
*
* PARAMS
*
- * DestIpAddress [In]
- * HopCount [In/Out]
- * MaxHops [In]
- * RTT [In/Out]
+ * DestIpAddress [In] destination address to get the info for
+ * HopCount [Out] retrieved hop count
+ * MaxHops [In] maximum hops to search for the destination
+ * RTT [Out] RTT in milliseconds
*
* RETURNS
- * FALSE
+ * Success: TRUE
+ * Failure: FALSE
*
+ * FIXME
+ * Stub, returns FALSE.
*/
BOOL WINAPI GetRTTAndHopCount(IPAddr DestIpAddress, PULONG HopCount, ULONG MaxHops, PULONG RTT)
{
@@ -1479,14 +1489,14 @@
/******************************************************************
* GetTcpStatistics (IPHLPAPI.@)
*
- * PARAMS
+ * Get the TCP statistics for the local computer.
*
- * pStats [In/Out]
+ * PARAMS
+ * pStats [Out] buffer for TCP statistics
*
* RETURNS
- *
- * DWORD
- *
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*/
DWORD WINAPI GetTcpStatistics(PMIB_TCPSTATS pStats)
{
@@ -1526,23 +1536,24 @@
/******************************************************************
* GetTcpTable (IPHLPAPI.@)
*
- * Returns a table of active TCP connections. On input, *pdwSize
- * is the size in bytes of pTcpTable. If this is less than required,
- * the function will return ERROR_INSUFFICIENT_BUFFER, and *pdwSize
- * will be set to the required byte size.
- * If bOrder is true, the returned table will be sorted, first by
- * local address and port number, then by remote address and port
- * number.
+ * Get the table of active TCP connections.
*
* PARAMS
- *
- * pTcpTable [In/Out]
- * pdwSize [In/Out]
- * bOrder [In]
+ * pTcpTable [Out] buffer for TCP connections table
+ * pdwSize [In/Out] length of output buffer
+ * bOrder [In] whether to order the table
*
* RETURNS
- * NO_ERROR on success, something else on failure.
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * NOTES
+ * If pdwSize is less than required, the function will return
+ * ERROR_INSUFFICIENT_BUFFER, and *pdwSize will be set to
+ * the required byte size.
+ * If bOrder is true, the returned table will be sorted, first by
+ * local address and port number, then by remote address and port
+ * number.
*/
DWORD WINAPI GetTcpTable(PMIB_TCPTABLE pTcpTable, PDWORD pdwSize, BOOL bOrder)
{
@@ -1591,14 +1602,14 @@
/******************************************************************
* GetUdpStatistics (IPHLPAPI.@)
*
- * PARAMS
+ * Get the UDP statistics for the local computer.
*
- * pStats [In/Out]
+ * PARAMS
+ * pStats [Out] buffer for UDP statistics
*
* RETURNS
- *
- * DWORD
- *
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*/
DWORD WINAPI GetUdpStatistics(PMIB_UDPSTATS pStats)
{
@@ -1632,22 +1643,23 @@
/******************************************************************
* GetUdpTable (IPHLPAPI.@)
*
- * Returns a table of active UDP connections. On input, *pdwSize
- * is the size in bytes of pUdpTable. If this is less than required,
- * the function will return ERROR_INSUFFICIENT_BUFFER, and *pdwSize
- * will be set to the required byte size.
- * If bOrder is true, the returned table will be sorted, first by
- * local address, then by local port number.
+ * Get a table of active UDP connections.
*
* PARAMS
- *
- * pUdpTable [In/Out]
- * pdwSize [In/Out]
- * bOrder [In]
+ * pUdpTable [Out] buffer for UDP connections table
+ * pdwSize [In/Out] length of output buffer
+ * bOrder [In] whether to order the table
*
* RETURNS
- * NO_ERROR on success, something else on failure.
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * NOTES
+ * If pdwSize is less than required, the function will return
+ * ERROR_INSUFFICIENT_BUFFER, and *pdwSize will be set to the
+ * required byte size.
+ * If bOrder is true, the returned table will be sorted, first by
+ * local address, then by local port number.
*/
DWORD WINAPI GetUdpTable(PMIB_UDPTABLE pUdpTable, PDWORD pdwSize, BOOL bOrder)
{
@@ -1701,13 +1713,15 @@
* never returns anything.
*
* PARAMS
- *
- * pIPIfInfo [In/Out]
- * dwOutBufLen [In/Out]
+ * pIPIfInfo [Out] buffer for adapter infos
+ * dwOutBufLen [Out] length of the output buffer
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI GetUniDirectionalAdapterInfo(PIP_UNIDIRECTIONAL_ADAPTER_ADDRESS pIPIfInfo, PULONG dwOutBufLen)
{
@@ -1720,17 +1734,21 @@
/******************************************************************
* IpReleaseAddress (IPHLPAPI.@)
*
- * NOTES
- * Since GetAdaptersInfo never returns adapters that have DHCP enabled,
- * this function does nothing.
+ * Release an IP optained through DHCP,
*
* PARAMS
- *
- * AdapterInfo [In/Out]
+ * AdapterInfo [In] adapter to release IP address
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * NOTES
+ * Since GetAdaptersInfo never returns adapters that have DHCP enabled,
+ * this function does nothing.
+ *
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI IpReleaseAddress(PIP_ADAPTER_INDEX_MAP AdapterInfo)
{
@@ -1744,17 +1762,21 @@
/******************************************************************
* IpRenewAddress (IPHLPAPI.@)
*
- * NOTES
- * Since GetAdaptersInfo never returns adapters that have DHCP enabled,
- * this function does nothing.
+ * Renew an IP optained through DHCP.
*
* PARAMS
- *
- * AdapterInfo [In/Out]
+ * AdapterInfo [In] adapter to renew IP address
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
+ *
+ * NOTES
+ * Since GetAdaptersInfo never returns adapters that have DHCP enabled,
+ * this function does nothing.
*
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI IpRenewAddress(PIP_ADAPTER_INDEX_MAP AdapterInfo)
{
@@ -1768,17 +1790,18 @@
/******************************************************************
* NotifyAddrChange (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Notify caller whenever the ip-interface map is changed.
*
* PARAMS
- *
- * Handle [In/Out]
- * overlapped [In/Out]
+ * Handle [Out] handle useable in asynchronus notification
+ * overlapped [In] overlapped structure that notifies the caller
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI NotifyAddrChange(PHANDLE Handle, LPOVERLAPPED overlapped)
{
@@ -1791,17 +1814,18 @@
/******************************************************************
* NotifyRouteChange (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Notify caller whenever the ip routing table is changed.
*
* PARAMS
- *
- * Handle [In/Out]
- * overlapped [In/Out]
+ * Handle [Out] handle useable in asynchronus notification
+ * overlapped [In] overlapped structure that notifies the caller
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI NotifyRouteChange(PHANDLE Handle, LPOVERLAPPED overlapped)
{
@@ -1814,19 +1838,20 @@
/******************************************************************
* SendARP (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Send an ARP request.
*
* PARAMS
- *
- * DestIP [In]
- * SrcIP [In]
- * pMacAddr [In/Out]
- * PhyAddrLen [In/Out]
+ * DestIP [In] attemp to obtain this IP
+ * SrcIP [In] optional sender IP address
+ * pMacAddr [Out] buffer for the mac address
+ * PhyAddrLen [In/Out] length of the output buffer
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI SendARP(IPAddr DestIP, IPAddr SrcIP, PULONG pMacAddr, PULONG PhyAddrLen)
{
@@ -1840,16 +1865,17 @@
/******************************************************************
* SetIfEntry (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Set the administrative status of an interface.
*
* PARAMS
- *
- * pIfRow [In/Out]
+ * pIfRow [In] dwAdminStatus member specifies the new status.
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI SetIfEntry(PMIB_IFROW pIfRow)
{
@@ -1865,16 +1891,17 @@
/******************************************************************
* SetIpForwardEntry (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Modify an existing route.
*
* PARAMS
- *
- * pRoute [In/Out]
+ * pRoute [In] route with the new information
*
* RETURNS
- * 0
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns NO_ERROR.
*/
DWORD WINAPI SetIpForwardEntry(PMIB_IPFORWARDROW pRoute)
{
@@ -1889,16 +1916,17 @@
/******************************************************************
* SetIpNetEntry (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Modify an existing ARP entry.
*
* PARAMS
- *
- * pArpEntry [In/Out]
+ * pArpEntry [In] ARP entry with the new information
*
* RETURNS
- * 0
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns NO_ERROR.
*/
DWORD WINAPI SetIpNetEntry(PMIB_IPNETROW pArpEntry)
{
@@ -1911,16 +1939,17 @@
/******************************************************************
* SetIpStatistics (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Toggle IP forwarding and det the default TTL value.
*
* PARAMS
- *
- * pIpStats [In/Out]
+ * pIpStats [In] IP statistics with the new information
*
* RETURNS
- * 0
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns NO_ERROR.
*/
DWORD WINAPI SetIpStatistics(PMIB_IPSTATS pIpStats)
{
@@ -1932,16 +1961,17 @@
/******************************************************************
* SetIpTTL (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Set the default TTL value.
*
* PARAMS
- *
- * nTTL [In]
+ * nTTL [In] new TTL value
*
* RETURNS
- * 0
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns NO_ERROR.
*/
DWORD WINAPI SetIpTTL(UINT nTTL)
{
@@ -1955,16 +1985,17 @@
/******************************************************************
* SetTcpEntry (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Set the state of a TCP connection.
*
* PARAMS
- *
- * pTcpRow [In/Out]
+ * pTcpRow [In] specifies connection with new state
*
* RETURNS
- * 0
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns NO_ERROR.
*/
DWORD WINAPI SetTcpEntry(PMIB_TCPROW pTcpRow)
{
@@ -1976,17 +2007,19 @@
/******************************************************************
* UnenableRouter (IPHLPAPI.@)
*
- * NOTES
- * Stub
+ * Decrement the IP-forwarding reference count. Turn off IP-forwarding
+ * if it reaches zero.
*
* PARAMS
- *
- * pOverlapped [In/Out]
- * lpdwEnableCount [In/Out]
+ * pOverlapped [In/Out] should be the same as in EnableRouter()
+ * lpdwEnableCount [Out] optional, receives reference count
*
* RETURNS
- * ERROR_NOT_SUPPORTED
+ * Success: NO_ERROR
+ * Failure: error code from winerror.h
*
+ * FIXME
+ * Stub, returns ERROR_NOT_SUPPORTED.
*/
DWORD WINAPI UnenableRouter(OVERLAPPED * pOverlapped, LPDWORD lpdwEnableCount)
{
More information about the wine-patches
mailing list