OmniClient User SWI interface specs		Revision 1.00, Nick 10/2/94
====================================		COMPANY CONFIDENTIAL

This draft is a version of ANT Ltd internal document 'SWI_Spec', edited to
include only details of user-level SWIs provided by the OmniClient system.
Please email comments to nas@ant.co.uk.

Terminology
-----------

omni_base is the SWI chunk as allocated by Acorn.
err_base  is the error block as allocated for OmniClient by Acorn.
print_id  is the unique 4-byte number that is used as an indentifier to
	  client programs that wish to print of current print jobs. The
	  print_id word is allocated by OmniClient filer, and is guaranteed
	  to be unique until the job is explicitly cleared - see SWI calls.
client    refers to an OmniClient protocol module
filer     refers to the OmniClient module
server    a remote networked *machine*
mount     a mounting of a server, which may be the whole filing system, or
	  just part of the directory tree (eg, NFS)
strings	  except where stated otherwise, all text strings should be null-
	  terminated, stored statically so that their position in memory
	  doesnt change during the lifetime of the Client (client
	  registration -> client deregistration). ie, C static
          maximum lengths, where given, EXCLUDE the terminator character.


Acorn allocated constants
-------------------------

omni_base 0x004a200
err_base  0x080d100

OmniClient module task
----------------------

The OmniClient relocatable module provides the following SWI calls for use
by client applications;

SWI omni_base+7 "Omni_Printers"
        On entry, R0 = reason code;
                        0 = list protocols supporting printers
                        1 = list protocol (FS names) supporting printers
                        2 = protocol print flags for protocol in R1
                       16 = list printer servers for protocol in R1
                       17 = list printers for protocol/server in R1/R2
                       18 = list all printers for protocol in R1
                  R1 = ptr to name of protocol (R0 = 2,16,17,18)
                  R2 = ptr to name of server for printers (R0 = 17)
                  R3 = ptr to buffer to fill with result string, or NULL
                  R4 = size of buffer in bytes, or -1 if not known 
        On exit,  R0 = protocol printing-support flags word (R0 = 2)
        	  R4 = size of buffer required for result string
	All other registers preserved on exit

        This SWI provides information about printer support in OmniClient.
        Currently the reason codes (R0=0,1,16,17,18) return a result string
        into a user buffer supplied as R3. It is expected that this is
        done as a 2-stage process to ensure that a large-enough buffer
        exists for the result string.
        
        The SWI is firstly called with R3=NULL,R4=-1, and the call returns
        with R4 containing the total size of buffer required (including 
        terminator). The buffer is allocated by the caller, and then the
        SWI is called the second time, with the new R3/R4.
        If no items are available, then R4=0 is returned.

        If R0 = 0, then the menu string contains the available protocol
        names that are registered as supporting printers. eg, "Acorn NFS,
        Acorn NetFS, ANT RemoteFS". R0 = 1 returns the same menu string,
        but with filing system names rather than full client descriptions.
        eg, "NFS, NetFS, RemoteFS".

	If R0 = 2, then the protocol printing-support flags word for the
	protocol named in R1 is returned. The flags word is of the format;

		bit 0 = 1, Client supports network printers
	              = 0, No printing support
	        bit 1 = 1, Password string required
	        bit 2 = 1, Needs file length before print job starts
	   bits 3..31 = *reserved* zero

        If R0 = 16, then the menu string contains the servers exported
        by the protocol named in R1. eg, "laser.net, print.cl".

        If R0 = 17, then the menu string contains the printers exported
        by the protocol named in R1, available as printers from the server
        named in R2. eg, "LibraryDM, Laser 600".

        If R0 = 18, then the menu string contains all the printers exported
        by the protocol named in R1. eg, "NetLaser, LibraryDM, Laser 600".
        This reason code lists all the printers available, irrespective of
        which network server they are connected to.

SWI omni_base+8 "Omni_CreateJob"
	On entry, R0 = ptr to protocol name
	          R1 = ptr to server name
	          R2 = ptr to printer name
	          R3 = ptr to user name, or NULL
	          R4 = ptr to password string, or NULL
                  R5 = ptr to options string, or NULL
                  R6 = size of print job (bytes), or 0 if not known
        On exit,  R0 = print_id of new job, if successful
                     = error block (V set), on error
	All other registers preserved on exit

        Submit a new job for network printing. Returns a unique 'print_id'
        word, or a pointer to an error block.

        The protocol name (R0) is the name as provided by SWI Omni_Printers
        (and registered as the 'client name'). eg, "Sun NFS". The user name,
        password and options string are optional, and may be NULL pointers.

        Some printing protocols require that the total size of the job is
        known before printing starts. If this is the case, they should be
        registered with OmniClient as requiring this. When a client
        program calls SWI Omni_PrinterInfo, reason code 2, it can determine
        whether a password field is required for this protocol, and whether
        the total size of the print job is required.

SWI omni_base+9 "Omni_SendJob"
	On entry, R0 = print_id
		  R1 = ptr to data block to send
		  R2 = size of data block to send
	On exit,  R2 = number of bytes not sent, or 0 for all done
	All other registers preserved on exit

        Send a block of data down network printer stream for a given active
        print_id word.

SWI omni_base+10 "Omni_EndJob"
	On entry, R0 = print_id
	All registers preserved on exit

        End a specified print job normally (ie, all data transmitted).

SWI omni_base+11 "Omni_AbortJob"
	On entry, R0 = print_id, or
		     = 0, to abort all jobs
	All registers preserved on exit

        Abort a specified print job, or all current jobs.

SWI omni_base+12 "Omni_JobStatus"
	On entry, R0 = print_id
	On exit,  R0 = preserved
		  R1 = local job status word (see below)
		  R2 = local job # bytes sent
		  R3 = error/status block ptr, or 0
		  R4 = remote job status word (see below)
		  R5 = remote job # bytes printed
		  R6 = error/status block ptr, or 0
	All other registers preserved on exit

        Get information on a specified print job. The status
        word (R1, R3) is currently defined as;

        	bit 0 = 0, no status available
        	      = 1, status information available
       	    bits 1..3 = 0, pending connection
       	    	      = 1, connection made, waiting for initial data
       	              = 2, sending bytes
       	              = 3, transfer complete
       	              = 4, job marked as temporary error
       	              = 5, job marked as terminal error
       	              =>5, *reserved*
	   bits 4..31 = *reserved* zero

SWI omni_base+13 "Omni_ClearJob"
	On entry, R0 = print_id, or
		     = 0, to clear all inactive jobs
	All registers preserved on exit

        Clear a specified print job, or all current inactive jobs. It is
        important to make this call once the client program has finished
        with the print job, and will no longer be calling Omni_JobStatus.
        eg, once it has marked the job as having been completed or having a
        terminal error. The status of a print job will reside in memory
        forever if this call is not made.

SWI omni_base+14 "Omni_PrinterInfo"
        On entry, R0 = ptr to name of protocol for printer
                  R1 = ptr to name of server
                  R2 = ptr to name of printer
        On exit,  R0 = flags word, or 0 if not available
	All other registers preserved on exit

        This SWI provides information about the facilities provided by a
        named printer. If information is not available then 0 is returned,
        or if the printer name is not valid, an error block ptr is returned.

        The flags word,is a set of bit fields that describe the printer type
  	and facilities provided (see PRM 3-595);

             	bit 0 = 1, Facilities information available,
                      = 0, information not available
            bits 1..7 = *reserved* zero
	        bit 8 = 1, Raw ASCII text
                bit 9 = 1, Postscript compatible
               bit 10 = 1, Epson FX80 or compatible
               bit 11 = 1, HP Laserjet or compatible
               bit 12 = 1, Integrex Colourjet
               bit 13 = 1, FAX modem
               bit 14 = 1, Direct drive laser printer
               bit 15 = 1, Caspel graphics language
               bit 16 = 1, PDumper interface
               bit 17 = 1, TeX 'DVI' files
               bit 18 = 1, Epson JX/Star LC10, HP Paintjet
          bits 19..31 = *reserved* zero

SWI omni_base+15 "Omni_EnumerateJobs"
	On entry, R1 = ptr to buffer for job list (word aligned)
	          R2 = size of buffer (words * 4)
	          R3 = 0, start enumerating jobs
	               not 0, continue enumerating jobs
	On exit,  R1 = ptr to next free byte in buffer, word aligned
	          R3 = 0, operation complete
	               not 0, buffer full, call again with this R3
	All other registers preserved on exit

	This SWI enumerates all printer jobs that OmniClient knows about,
	returning a list of their print_id values in consecutive words of
	the supplied buffer, until the buffer is full or the enumeration is
	complete. This allows printer managment applications to gain access
	to print_id handles of jobs even if they were started using the
	OmniPrint filing system, or by another application using SWI
	Omni_CreateJob.
       
	If R3 is not 0 on exit, then the enumeration is not complete
	(buffer full), and the reason code is called again with the
	new R3 value. This process continues until the enumeration
	is complete.


nas@ant.co.uk
---
Document ends

