server - WIN
The server program is intended for computers that run as servers. It
is independent of WIN and can be run with or without it. The
communications protocol used by the server is compatible with that
used by WIN comm
system, and the browse and email applications.
The server runs by overriding the os.get_event function. When run,
it returns immediately to the command line, but is still running in
the background, responding to incoming request. Once started the
server cannot be stopped, except by rebooting the computer.
To run the server with WIN, run the server program before loading
WIN. To run the server without WIN it can be started at anytime, but
typically is from the /boot file.
Note that if the server is run with WIN installed, a computer cannot
communicate with itself over a comm connection.
Options may be set, in the form of global variables, to customize
the server's connection. They must be defined before running the
server program. The server program searches for /server.cfg,
and runs it if found.
SERVER_PASSWORD |
string |
The server access password when accessing the
server via the administration messages. If not specified the
default is "admin". |
SERVER_NETWORK |
string |
This is the comm application identifier the
server will respond to. If not specified the default is "wide_area_network". |
SERVER_TIMEOUT |
number |
The timeout count for the server connection.
If not specified the default is 5. |
SERVER_ROOT |
string |
This is the local folder (full path) that is
the root of the files requested. This acts a the root for
the path of incoming request. If not specified the default
is "/public". The folder path
must exist on the server to operate. |
ACCOUNTS_ROOT |
string |
This is the local folder (full path) that is
the root of the (email) accounts' folders. Data for each
account is stored under its own folder, of the account name,
under this folder. If not specified the default is "/accounts". |
See also API
Reference, WIN.
Functions
create_account
result create_account (account, password)
Creates a new (email) account.
Parameters
account |
string |
The name of the account to create. |
password |
string/nil |
Optionally an initial password for the
account. If omitted defaults to "1234".
|
Returns
result |
boolean |
True if the account was successfully created,
otherwise false. |
Remarks
This function is globally available.
See create_account.
top
delete_account
result delete_account (account)
Deletes an (email) account.
Parameters
account |
string |
The name of the account to delete. |
Returns
result |
boolean |
True if the account was deleted, false if not
(not found). |
Remarks
This function is globally available.
See delete_account.
top
set_account_password
result set_account_password (account, password)
Sets an (email) account's password.
Parameters
account |
string |
The account to set. |
password |
string |
The new password for the account. |
Returns
result |
boolean |
True if the password was successfully set,
otherwise false. |
Remarks
This function is globally available.
See reset_password.
top
Messages
account_password
account_password
Account access to change the account's password.
Message Fields (msg)
recipient |
string/number |
The server's computer label or id. Typically
the server's label, used as a domain name. |
application |
string |
The server's network. |
context |
string |
"account_password" |
data |
table |
Must be a table with the following fields. |
data.account |
string |
The account name. |
data.password |
string |
The existing password. |
data.new_password |
string |
The new password. |
Remarks
If for some reason (the password is incorrect, the account name was
not found, etc.) the message is not received by the server.
top
create_account
create_account
Remote server administration message to create a new (email)
account.
Message Fields (msg)
recipient |
string/number |
The server's computer label or id. Typically
the server's label, used as a domain name. |
application |
string |
The server's network. |
context |
string |
"create_account" |
data |
table |
Must be a table with the following fields. |
data.password |
string |
The server access password. |
data.account |
string |
The name of the account to create. |
data.client_password
|
string |
Optionally an initial password for the
account. If omitted defaults to "1234". |
Remarks
If for some reason (the access password is incorrect, the account
name already exists, etc.) the message is not received by the
server.
See create_account.
top
delete_account
delete_account
Remote server administration message to delete an (email) account.
Message Fields (msg)
recipient |
string/number |
The server's computer label or id. Typically
the server's label, used as a domain name. |
application |
string |
The server's network. |
context |
string |
"delete_account" |
data |
table |
Must be a table with the following fields. |
data.password |
string |
The server access password. |
data.account |
string |
The name of the account to delete. |
Remarks
If for some reason (the access password is incorrect, the account
name does not exists, etc.) the message is not received by the
server.
See delete_account.
top
directory_create
directory_create
Remote server administration message to creates a new directory
(folder) on the server.
Message Fields (msg)
recipient |
string/number |
The server's computer label or id. Typically
the server's label, used as a domain name. |
application |
string |
The server's network. |
context |
string |
"directory_create" |
data |
table |
Must be a table with the following fields. |
data.password |
string |
The server access password. |
data.path |
string |
Server directory path to create. This path is
interpreted from the SERVER_ROOT folder. |
Remarks
If for some reason (the password is incorrect, the path was not
valid, etc.) the message is not received by the server.
top
email_delete
email_delete
Requests the deletion of an email stored on the server.
Message Fields (msg)
recipient |
string/number |
The server's computer label or id. Typically
the server's label, used as a domain name. |
application |
string |
The server's network. |
context |
string |
"email_delete" |
data |
table |
Must be a table with the following fields. |
data.account |
string |
The account name. |
data.password |
string |
The account password. |
data.id |
string |
The email identifier sent in the email_response
message. |
Remarks
If for some reason (the password is incorrect, the account name was
not found, etc.) the message is not received by the server.
top
email_request
email_request
Requests the download of any emails stored on the server.
Message Fields (msg)
recipient |
string/number |
The server's computer label or id. Typically
the server's label, used as a domain name. |
application |
string |
The server's network. |
context |
string |
"email_request" |
data |
table |
Must be a table with the following fields. |
data.account |
string |
The account name. |
data.password |
string |
The account password. |
data.application |
string |
The comm application identifier the
server will send the response as. |
Remarks
A client application must specify an application identifier for the
returning messages. This means the client application opens a comm connection and
registers two interest (usually with window:want_messages).
One with the application identifier the server is operating with,
for sent notifications, and one with the client application
identifier for receiving from the server.
The server responds with a "email_response" message for
each email stored on the server, using the data.application value in
the return message. The data key of the message returned by the
server contains the following keys:
{
account = string,
id = string,
email =
{
recipient = string,
sender = string,
time = number, -- optional, (os.time ())
subject = string, -- optional
message = string
}
}
For each successfully received email the client application should
respond with an email_delete
message, passing the data.id from the "email_request"
message.
If for some reason (the password is incorrect, the account name was
not found, etc.) the message is not received by the server.
top
email_send
email_send
Sent to a server to store an email intended for an account on that
server.
Message Fields (msg)
recipient |
string/number |
The server's computer label or id. Typically
the server's label, used as a domain name. |
application |
string |
The server's network. |
context |
string |
"email_send" |
data |
table |
Must be a table with the following fields. |
data.account |
string |
The receiving account's name. |
data.email |
table |
Must be a table with the following fields. |
data.email.recipient |
string |
The receiver's email address. |
data.email.sender |
string |
The sender's email address. |
data.email.message |
string |
The body of the message. |
data.email.subject |
string |
Optionally a subject line. |
data.email.time |
number |
Optionally a time stamp of when the email was
sent. (os.time ()). |
Remarks
If for some reason (the account name was not found, etc.) the
message is not received by the server.
top
file_delete
file_delete
Remote server administration message to delete a file or folder.
Message Fields (msg)
recipient |
string/number |
The server's computer label or id. Typically
the server's label, used as a domain name. |
application |
string |
The server's network. |
context |
string |
"file_delete" |
data |
table |
Must be a table with the following fields. |
data.password |
string |
The server access password. |
data.path |
string |
Server path of the file or folder to delete.
This path is interpreted from the SERVER_ROOT
folder. |
Remarks
If for some reason (the access password is incorrect, the path is
invalid, etc.) the message is not received by the server.
See file_upload.
top
file_upload
file_upload
Remote server administration message to upload a file.
Message Fields (msg)
recipient |
string/number |
The server's computer label or id. Typically
the server's label, used as a domain name. |
application |
string |
The server's network. |
context |
string |
"file_upload" |
data |
table |
Must be a table with the following fields. |
data.password |
string |
The server access password. |
data.path |
string |
Server path to upload the file to. This path
is interpreted from the SERVER_ROOT folder. |
data.content |
string |
The contents of the uploaded file, to store
on the server. |
Remarks
If for some reason (the access password is incorrect, the path is
invalid, etc.) the message is not received by the server.
See file_delete.
top
ftp_request
ftp_request
Requests the download of a file, generally to save directly to disk.
Message Fields (msg)
recipient |
string/number |
The server's computer label or id. Typically
the server's label, used as a domain name. |
application |
string |
The server's network. |
context |
string |
"ftp_request" |
data |
table |
Must be a table with the following fields. |
data.path |
string |
Path of the requested file. This path is
interpreted from the SERVER_ROOT folder. If the
path ends in a "/", is a
folder or is empty, the server will check for a file in the
respective folder first as "index.html",
then "index.htm" and then "index.txt". |
data.application |
string |
The comm application identifier the
server will send the response as. |
Remarks
A client application will usually generated a unique application
identifier for each running instance, so responses from the server
are received by the requesting client and application only. This
means the client application opens a comm connection and registers two interest
(usually with window:want_messages).
One with the application identifier the server is operating with,
for sent notifications, and one with the generated unique
application identifier for receiving from the server.
The server responds with a "ftp_response"
message using the data.application value in the return message. The
data key of the message returned by the server contains two keys;
path and content. The path is the full address, including the
domain, of the file. The content is a string containing the contents
of the requested file. If the requested file is not found by the
server the requesting message is not received.
The domain name of a server is usually its computer label, which
should be set. For example, assuming the server's label is my.com,
with the default network set up. A request for the file at /public/here/there.dat
with ftp protocol from the client:
wnd:send_message ("my.com", "wide_area_network", "ftp_request",
{ path = "/here/there.dat", application = "my_unique_app_id" },
sendConnection)
The context of the message returned by the server to the connection
with the application identifier "my_unique_app_id"
will be "ftp_response", and the path
key in the data of the message will be "my.com/here/there.dat".
See http_request.
top
http_request
http_request
Requests the download of a file, generally a html or text file for
viewing.
Message Fields (msg)
recipient |
string/number |
The server's computer label or id. Typically
the server's label, used as a domain name. |
application |
string |
The server's network. |
context |
string |
"http_request" |
data |
table |
Must be a table with the following fields. |
data.path |
string |
Path of the requested file. This path is
interpreted from the SERVER_ROOT folder. If the
path ends in a "/", is a
folder or is empty, the server will check for a file in the
respective folder first as "index.html",
then "index.htm" and then "index.txt". |
data.application |
string |
The comm application identifier the server
will send the response as. |
Remarks
A client application will usually generated a unique application
identifier for each running instance, so responses from the server
are received by the requesting client and application only. This
means the client application opens a comm connection and registers
two interest (usually with window:want_messages).
One with the application identifier the server is operating with,
for sent notifications, and one with the generated unique
application identifier for receiving from the server.
The server responds with a "http_response"
message using the data.application value in the return message. The
data key of the message returned by the server contains two keys;
path and content. The path is the full address, including the
domain, of the file. The content is a string containing the contents
of the requested file. If the requested file was not found by the
server the path is still the request path, but the content is a file
not found message page.
The domain name of a server is usually its computer label, which
should be set. For example, assuming the server's label is my.com,
with the default network set up. A request for the file at /public/here/there.txt
with http protocol from the client:
wnd:send_message ("my.com", "wide_area_network", "http_request",
{ path = "/here/there.txt", application = "my_unique_app_id" },
sendConnection)
The context of the message returned by the server to the connection
with the application identifier "my_unique_app_id"
will be "http_response", and the path
key in the data of the message will be "my.com/here/there.txt".
See ftp_request.
top
listing_request
listing_request
Requests a listing of the files and folders (directories) of the
given folder path.
Message Fields (msg)
recipient |
string/number |
The server's computer label or id. Typically
the server's label, used as a domain name. |
application |
string |
The server's network. |
context |
string |
"listing_request" |
data |
table |
Must be a table with the following fields. |
data.password |
string |
The server access password. |
data.path |
string |
Server folder path to return the file and
folder listing of. This path is interpreted from the SERVER_ROOT
folder. |
data.application |
string |
The comm application identifier the
server will send the response as. |
Remarks
A client application must specify an application identifier for the
returning messages. This means the client application opens a comm connection and
registers two interest (usually with window:want_messages).
One with the application identifier the server is operating with,
for sent notifications, and one with the client application
identifier for receiving from the server.
The server responds with a "listing_response"
message, using the data.application value in the return message. The
data key of the message returned by the server contains the
following keys:
{
path = string,
files = table, -- indexed list of file names
folders = table -- indexed list of folder names
}
If for some reason (the password is incorrect, the path was not
valid, etc.) the message is not received by the server.
top
reset_password
reset_password
Remote server administration message to reset an (email) account's
password.
Message Fields (msg)
recipient |
string/number |
The server's computer label or id. Typically
the server's label, used as a domain name. |
application |
string |
The server's network. |
context |
string |
"reset_password" |
data |
table |
Must be a table with the following fields. |
data.password |
string |
The server access password. |
data.account |
string |
The name of the account to reset. |
data.client_password |
string |
Optionally the reset password for the
account. If omitted defaults to "1234". |
Remarks
If for some reason (the access password is incorrect, the account
name was not found, etc.) the message is not received by the server.
See set_account_password.
top
See also API
Reference, WIN.