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.