Re: SIP API spec (hostname2address function)

["Dean D. Throop" <[e-mail]>]

>From: [e-mail] (Bob Gilligan)
>Message-Id: <[e-mail]>
>To: [e-mail], [e-mail]
>Subject: SIP API spec
>
>Here's a first draft of a spec for changes to BSD APIs to support SIP
>and IPAE.  Send comments and suggestions to me.
>

I think this specification is a good idea.  While we are proposing 
changing gethostbyname we should solve some other problems at the 
same time.  

I agree with Craigs comment of
>
>How about hostname2addr(), and hostbyaddr(), and addr2ascii()?
>    <for gethostbyname(), gethostbyaddr(), inet_ntoa(), and make
>    them all take an AF_* value so that they can be made address
>    format independent>
>

For hostname2addr, I would like the caller to supply an ordered list 
of AF_* values which the caller will accept.  The alternative is for 
the user to loop through all the address type of interest.  Since
each call searches a data base, it would be nicer to just do one search.

The new interface should also require the caller to pass in the
buffer for the hostent structure.  Threads are coming and interfaces
that return static variables are generally being replaced with
new interfaces to support multi-threaded programs.  


How about:

struct hostent *hostname2address(
			char *hostname, 
			int *type_array,
			char *buffer,
			int buffer_length)


hostname2address returns a hostent structure containing the address
for the specified host.  The name is looked up in the current
domain unless the name is a fully qualified name.

hostname: 	is a zero byte terminated ascii character 
	name of requested host.

type_array: is pointer to array of AF_* values identifying the
	address types the caller will accept.  The end of the list
	is indicated by a type of AF_UNSPEC.  The list is ordered
	in that the first entry in the list is the most preferred,
	the last the least preferred.

buffer:	is a pointer to a buffer supplied to hold the return value.

buffer_length: is the length of the buffer in bytes.
	The buffer should be at least 
		sizeof(struct hostent)
		    +
		5 * sizeof(char **)
		    +
		4 * sizeof(struct sockaddr)
		    +
		9 * sizeof(long)
	bytes long.
  	If the caller expects more than 4 addresses, a larger
	buffer should be supplied as lookups of those
	hosts will fail.  (The 9*sizeof(long) suggestion
	is to allow for any necessary structure alignment 
	the function may need.)

The return value is a hostent structure if an address was found
for the specified host.  A value of NULL will indicate no address
information available.

If a return value was NULL, the static variable h_errno will
contain an error code indicating the failure.  We probably
would like to add the following error code:

HOSTENT_BUFFER_TOO_SHORT 
to return if the caller passes in a buffer that is too short, and

HOSTADDRESS_ACCESS_DENIED
to return if the caller doesn't have access to lookup hostnames.

Dean Throop		[e-mail]