Description
The gethostbyaddr function returns information about a host identified by address. The host information is returned in a structure of type hostent. This structure is allocated by the WinSock2 library, and your program should not attempt to modify or de-allocate, the structure or any of it's components.
Only one copy of the hostent structure is allocated per calling thread, and since Irie Pascal programs only have one thread, there will be only one copy of this structure allocated for your program. As a result, you should copy any host information you need from the structure before calling any other Windows Sockets functions.
Declaration
The system include file WinSock2.inc contains the following declaration for the hostent and p_hostent types and the gethostbyaddr function:
hostent = packed record
h_name : address;
h_aliases : address;
h_addrtype : shortint;
h_length : shortint;
h_addr_list : address;
end;
p_hostent = ^hostent;
function gethostbyaddr(addr : address; len, typ : integer) : address;
external dll='ws2_32.dll';
Arguments
The First Argument
The first argument passed to the gethostbyaddr function is the operating system address of the buffer containing the address of the host you want to get information about. The address stored in the buffer is not stored as a string, it is stored as a numeric value in in network byte order. The type of this argument is the built-in type address, so you must use the built-in function addr to get the operating system address of the buffer.
If you have the address of a host, as a null-terminated string, and you want to get information about that host then you should do the following:
The second argument passed to the gethostbyaddr function is the length of the host address in the buffer pointed to be the first argument.
The Third Argument
The third argument passed to the gethostbyaddr function is the type of the host address in the buffer pointed to be the first argument.
Return Values
The gethostbyaddr function returns a pointer to the hostent structure that contains the host information, if the call is successful. If the call fails then the value nil is returned, and in this case you can use the WSAGetLastError function to retrieve a code that identifies the error that caused the call to fail.
Example
The following procedure was taken from one of the sample programs distributed with Irie Pascal and shows one way to use the gethostbyaddr function.
//PUPOSE: Given the IP address of a host perform a reverse DNS lookup.
// 1. strIPAddress - contains the name of the host
procedure ReverseDNSLookUp(strIPAddress : cstring);
var
IPAddress : in_addr;
pHostEnt : p_hostent;
begin
IPAddress := inet_addr(addr(strIPAddress));
if IPAddress = INADDR_NONE then
writeln('Invalid IP address')
else
begin
pHostEnt := gethostbyaddr(addr(IPAddress), sizeof(IPAddress), AF_INET);
if pHostEnt = nil then
writeln('Can not find address ''', hex(IPAddress), '''')
else
DisplayHostEntInfo(pHostEnt);
end;
end;
The procedure DisplayHostEntInfo is defined by the sample program and displays the host information stored in the hostent structure. See the gethostbyname function for the actual DisplayHostEntInfo procedure.
Reference Information
The authoritative source of information about the WinSock2 library is the Microsoft Developers Network (MSDN). You can access the MSDN on the Microsoft website at msdn.microsoft.com.