int inquire(string host, mixed port, int socketmode, mixed sendtext,
string func, mixed callto, int fast, int hangup, int timeout);
--OR--
int inquire(string host, mixed port, int socketmode, mixed sendtext,
function func, int fast, int hangup, int timeout);
In either case, the final three arguments are entirely optional.
This gets called by external objects.
Arguments:
host : Which machine we're connecting to. Numeric IP
is preferable, but either will work.
port : Which port on the host. Can be string or int.
socketmode : STREAM, STREAM_BINARY, etc.
sendtext : the data to transmit when the connection is made.
Can be string or buffer. If it is "", only a
newline will be sent. If it is 0, no data will
be sent (receive-only connection).
func : If it's a function pointer, any returned data
from the remote host is sent to this function.
If it's a string (and the name of a function),
That function is called in callto.
Prototype should be:
void func(int fd, int success, mixed response);
- or -
void func(int fd, int success, mixed response,
string wordip, string numericip);
See below for when to use which.
callto : Only used if func is a string representation of
a function. This argument can be omitted if func
is a function pointer. It can be an object pointer
or a string.
fast : Defaults to 0 if omitted, of course. When 0,
resolve() will always be called on 'host', and
its returns will be passed with the data when
the time comes. In this case, the callback function
should be in the form:
void func(int fd, int success, mixed response,
string wordip, string numericip);
If fast == 1, 'host' is assumed to be numeric,
and there is no delay for the running of resolve().
The callback should be:
void func(int fd, int success, mixed response);
hangup : If true, only one packet is expected from the
remote machine. Close the connection (if not
already closed) as soon as this packet is received,
and return the received data via the callback.
timeout : Defaults to whatever value TIMEOUT holds. If
included, a timeout will be considered to have
occurred after 'timeout' seconds, at which time
any received data will be sent to the callback,
or failure will be reported. This would be useful
for ports that are not smart enough to 'hang up'
on you when they're done.
Returns:
Returns an error code specific to inquired if one of the arguments
was invalid. Look at <inquire_errors.h> for information. The
inquire_error() macro in the .h translates it into text. May also
return a true socket error if fast == 1. inquire_error() will
translate this sort of error as well.
0 : An unknown error has occurred. This shouldn't ever happen.
<0 : An error has occurred. May either be invalid arguments
to inquire() or a socket error of some sort. Use
inquire_error() to get a plain-text version of the errormsg.
>0 : Successful beginnings of a connection. The return number
is the fd of the socket. May be useful for indexing.
Errors after the return of inquire() will trigger a calling
of func() will a 'success' value of <= 0. 'response' will
hold a text-version of the error message. Any 'success' value
> 0 means the transmission was successful, and 'response' will
hold what the host responded.