Manipulating File Names ||
Primitives and EEL Subroutines ||
Epsilon User's Manual and Reference >
Primitives and EEL Subroutines >
File Primitives >
int telnet_host(char *host, int port, char *buf)
telnet_send(int id, char *text)
do_telnet(char *host, int port, char *buf)
buffer int telnet_id;
int telnet_server_echoes(int id)
Epsilon provides various commands that use Internet FTP, Telnet and
similar protocols. This section documents how some parts of this
All Internet-related functions that retrieve text in the background
and insert it in a buffer do so at the buffer's type_point, just
like Epsilon's process functions.
First, Epsilon provides the primitives telnet_host( ) and
telnet_send( ) for use with the Telnet protocol. The
telnet_host( ) function establishes a connection to a host on the
specified port, and using the indicated buffer. It returns an
identification code. The telnet_send( ) function can use this
code to send text to the host. To kill the telnet job, call
telnet_send( ) and pass NULL as the text. Commands normally call
the telnet_host( ) function through the do_telnet( )
subroutine, which records the telnet identification code in the
telnet_id variable, and does other
The telnet_server_echoes( ) primitive accepts a telnet
identification code as above, and returns
1 if the server on that
connection is currently set to echo characters sent to it, or
it is not.
int finger_user(char *user, char *host, char *buf)
int http_retrieve(char *resource, char *host, int port,
char *auth, char *buf, int flags)
int download_file_to_disk(char *url, char *fname, int sz)
The finger_user( ) primitive uses the Finger protocol to
retrieve information on a particular user (if the host is running a
Finger server). It takes the user name, the host, and the name of a
buffer in which to put the results.
The http_retrieve( ) primitive uses the HTTP protocol to
retrieve a page from a web site. It takes a resource name (the final
part of a URL), a host, port, an authorization string (for
password-protected pages) and destination buffer name, plus a set of
HTTP_RETRIEVE_WAIT flag tells the function not
to return until the transfer is complete. Without this flag the
function begins the transfer and lets it continue in the background.
HTTP_RETRIEVE_ONLY_HEADER flag tells the function to
retrieve only the header of the web page, not the body. Without this
flag Epsilon will retrieve both; the first blank line retrieved
separates the two.
If the http_force_headers variable is non-null and
non-empty, http_retrieve( ) uses its contents for the HTTP request
it sends to the remote system. It should contain a complete, valid
HTTP request. But if it starts with a
+ character, then Epsilon
simply adds the rest of its contents to each HTTP request. It should
contain a series of header lines, each terminated by \r\n.
The download_file_to_disk( ) subroutine retrieves the
document from the specified
url, then writes it to the disk file
fname. It returns
0 on success,
1 if retrieving the
file failed, or an error code from writing the file. (A 404 or other
numeric error when retrieving a web page is treated as a success, as
long as it returns a page of some sort. Check the HTTP Headers buffer
for the error code if needed.) The
sz parameter should be the
file's expected size; if nonzero, the subroutine displays progress
The show_url( ) subroutine displays the specified URL in a
web browser, aborting with an error if it couldn't. The similar
try_show_url( ) subroutine displays the URL in a browser,
returning zero if it couldn't, nonzero if it could. A success code
indicates merely that Epsilon was able to find a browser, not that the
specified page exists.
int is_remote_buffer(int buf)
buffer char *buffer_url;
The is_remote_buffer( ) subroutine returns nonzero if the
specified buffer has a telnet or ssh session running, or whose file
name refers to a remote file (one accessed via scp or ftp).
In buffers with a telnet or ssh session, Epsilon sets the
buffer-specific buffer_url variable to the URL used to
create it. This is so it can restart the session later if necessary.
int ftp_op(char *buf, char *log, char *host, int port,
char *usr, char *pwd, char *file, int op)
int do_ftp_op(char *buf, char *host, char *port,
char *usr, char *pwd, char *file, int op)
The ftp_op( ) primitive uses the FTP protocol
to send or retrieve files or get directory listings. It takes the
destination or source buffer name, the name of a log buffer, a host
computer name and port number, a user name and password, a file name,
and an operation code that indicates what function it should perform
The do_ftp_op( ) subroutine is similar to ftp_op( ), but
it chooses the name of an appropriate FTP Log buffer, instead of
taking the name of one as a parameter. Also, it arranges for the
appropriate ftp_activity( ) function (see below) to be called,
arranges for character-coloring the log buffer, and initializes the
ftp_job structure that Epsilon uses to keep track of each FTP job.
FTP_RECV operation code retrieves the specified file
FTP_SEND code writes the buffer to the specified
file name. The
FTP_LIST code retrieves a file listing from
the host of files matching the specified file pattern or directory
FTP_MISC code indicates that the file name
actually contains a series of raw FTP commands to execute after
connecting and logging in, separated by newline characters. Epsilon
will execute the commands one at a time.
You can combine one of the above codes with some bit flags that
modify the operation. Use the
FTP_OP_MASK macro to mask
off the bit flags below and extract one of the operation codes above.
Normally ftp_op( ) returns immediately, and each of these
operations is carried out in the background. Add the code
FTP_WAIT to any of the above codes, and the subroutine will
not return until the operation completes.
FTP_ASCII bit flag modifies the FTP_RECV and
FTP_SEND operations. It tells Epsilon to perform the transfer
in ASCII mode. By default, all FTP operations use binary mode, and
Epsilon performs any needed line translation itself. But this
doesn't work on some host systems (VMS systems, for example). See
the ftp-ascii-transfers variable for more information.
FTP_USE_CWD bit flag modifies how Epsilon uses the file
name provided for operations like FTP_RECV, FTP_SEND, and
FTP_LIST. By default, Epsilon sends the file name to the host
as-is. For example, if you try to read a file
dirname/another/myfile, Epsilon sends an FTP command like
dirname/another/myfile. Some hosts (such as VMS) use a different
format for directory names than Epsilon's dired directory
editor understands. So with this flag, Epsilon breaks a file name
apart, and translates a request to read a file such as
dirname/another/myfile into a series of commands to change
dirname, then to
another, and then to retrieve
FTP_PLAIN_LIST bit flag makes
FTP_LIST operations send a
LIST command; without it, they
LIST -a command so the remote system includes hidden files.
The ftp-compatible-dirs variable controls these bits.
int url_operation(char *file, int op)
The url_operation( ) subroutine parses a URL and begins
an Internet operation with it. It takes the URL and an operation
code as described above for ftp_op( ). If the code is
FTP_RECV, then the URL may indicate a service type of telnet://,
http://, or ftp://, but if the code is FTP_SEND or
FTP_LIST, the service type must be ftp://. It can modify the
passed URL in place to put it in a standard form. It calls one of
the functions do_ftp_op( ), http_retrieve( ), or
do_telnet( ) to do its work.
ftp_misc_operation(char *url, char *cmd)
The ftp_misc_operation( ) subroutine uses the
do_ftp_op( ) subroutine to perform a series of raw FTP commands.
It takes an ftp:// URL (ignoring the file name part of it) connects
to the host, logs in, and then executes each of the newline-separated
FTP commands in
cmd. Dired uses this function to delete or move
a group of files.
buffer int (*when_net_activity)();
net_activity(int activity, int buf, int from, int to)
As Epsilon performs Internet functions, it calls an EEL function to
advise it of its progress. The buffer-specific variable
when_net_activity contains a function pointer to the
function to call. Epsilon uses the value of this variable in the
destination buffer (or, in the case of the NET_LOG_WRITE and
NET_LOG_DONE codes below, the log buffer). If the variable is
zero in a buffer, Epsilon won't call any EEL function as it proceeds.
The EEL function will always be called from within a call to
getkey( ) or delay( ), so it must save any state information
it needs to change, such as the current buffer, the position of
point, and so forth, using
save_var. The subroutine
net_activity() shown above indicates what parameters the function
should take--there's not actually a function by that name.
activity parameter indicates the event that just occurred. A
NET_RECV indicates that Epsilon has just received
some characters and inserted them in a buffer. The
tells which buffer is involved. The
indicate the new characters. A value of
that the net job running in buffer
buf has finished. The above
are the only activity codes generated for HTTP, Telnet, or Finger
FTP jobs have some more possible codes.
that another block of text has been sent. In this case,
indicates that number of bytes sent already from buffer
to indicates the total number of bytes to be sent. The code
NET_LOG_WRITE indicates that some more text has been
written to the log buffer
buf, in the range
Finally, the code
NET_LOG_DONE indicates that the FTP
operation has finished writing to the log buffer. It occurs right
after a NET_DONE call on FTP jobs.
ftp_activity(int activity, int buf, int from, int to)
finger_activity(int activity, int buf, int from, int to)
telnet_activity(int activity, int buf, int from, int to)
buffer int (*buffer_ftp_activity)();
The file epsnet.e defines the
when_net_activity functions shown
above, which provide status messages and similar things for each type
of job. The ftp_activity( ) subroutine also calls a
subroutine itself, defined just like these functions, through the
dired command uses this to arrange for normal FTP activity
processing when retrieving directory listings, but also some
processing unique to dired.
int gethostname(char *host, ?int method)
The gethostname( ) primitive
host to the computer's host name and returns
0. If it
can't for any reason, it returns 1 and sets
host to "?".
method parameter controls which type of host name Epsilon
retrieves. By default, it uses the machine's locally-configured host
name. A value of
3 makes it instead retrieve the host's fully
qualified domain name using DNS. Values of
2 make it do
this only under Windows or Unix, respectively. Retrieving the DNS
name in some network configurations can cause on-demand auto-dialing
or delays if the machine's DNS server isn't accessible.
Manipulating File Names ||
Primitives and EEL Subroutines ||
Copyright (C) 1984, 2020 by Lugaru Software Ltd. All rights reserved.