=head1 NAME

gspool_getspd - get the default permissions

=head1 SYNOPSIS

=for man
\&\fB#include <gspool.h>\fR
.PP

=for html
<STRONG>#include &lt;gspool.h&gt;</STRONG>
<BR>

B<int gspool_getspd(const int> I<fd>B<, struct apisphdr *>I<res>B<)>

=head1 DESCRIPTION

The B<gspool_getspd()> function is used to retrieve the defaults
privileges, form types etc for new users on the host with which the
API is communicating.

I<fd> is a file descriptor previously returned by B<gspool_open>

I<res> is a descriptor which upon return will contain the the default
user privileges. The structure B<apisphdr> is defined in F<gspool.h>
and contains the following elements:

=for html
<A NAME="Apisphdr_def"></a>
<div class=indtab>
<table border=0 cellpadding=1 cellspacing=0 summary="Header">
<tr>
<th align=left class=dense>Type</th>
<th align=left class=dense>Field</th>
<th align=left class=dense>Description</th>
</tr>
<tr>
<td class=dense><span class=FileName>long</span></td>
<td class=dense><span class=FileName>sph_lastp</span></td>
<td class=dense>Time last read password file</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>sph_minp</span></td>
<td class=dense>Minimum priority</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>sph_maxp</span></td>
<td class=dense>Maximum priority</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>sph_defp</span></td>
<td class=dense>Default priority</td>
</tr>
<tr>
<td class=dense><span class=FileName>char []</span></td>
<td class=dense><span class=FileName>sph_form</span></td>
<td class=dense>Default form type</td>
</tr>
<tr>
<td class=dense><span class=FileName>char []</span></td>
<td class=dense><span class=FileName>sph_formallow</span></td>
<td class=dense>Allowed form type pattern</td>
</tr>
<tr>
<td class=dense><span class=FileName>char []</span></td>
<td class=dense><span class=FileName>sph_ptr</span></td>
<td class=dense>Default printer</td>
</tr>
<tr>
<td class=dense><span class=FileName>char []</span></td>
<td class=dense><span class=FileName>sph_ptrallow</span></td>
<td class=dense>Allowed printer pattern</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned long</span></td>
<td class=dense><span class=FileName>sph_flgs</span></td>
<td class=dense>Privilege flag</td>
</tr>
<tr>
<td class=dense><span class=FileName>classcode_t</span></td>
<td class=dense><span class=FileName>sph_class</span></td>
<td class=dense>Class of printers</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>sph_cps</span></td>
<td class=dense>Maximum copies allowed</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>sph_version</span></td>
<td class=dense>Release of GNUspool</td>
</tr>
</table>
</div>

=for man
.Ip "long sph_lastp" 8
Time last read password file
.Ip "unsigned char sph_minp" 8
Minimum priority
.Ip "unsigned char sph_maxp" 8
Maximum priority
.Ip "unsigned char sph_defp" 8
Default priority
.Ip "char sph_form[]" 8
Default form type
.Ip "char sph_formallow[]" 8
Allowed form type pattern
.Ip "char sph_ptr[]" 8
Default printer
.Ip "char sph_ptrallow[]" 8
Allowed printer pattern
.Ip "unsigned long sph_flgs" 8
Privilege flag
.Ip "classcode_t sph_class" 8
Class of printers
.Ip "unsigned char sph_cps" 8
Maximum copies allowed
.Ip "unsigned char sph_version" 8
Release of GNUspool

The C<spu_flgs> field will contain a combination of the following:

=for html
<div class=indtab>
<table border=0 cellpadding=1 cellspacing=0 summary="spu_flgs">
<tr>
<td class=dense><span class=FileName>PV_ADMIN</span></td>
<td class=dense>Administrator (edit admin file)</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_SSTOP</span></td>
<td class=dense>Can run sstop (can stop scheduler)</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_FORMS</span></td>
<td class=dense>Can use other forms than default</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_CPRIO</span></td>
<td class=dense>Can change priority on queue</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_OTHERJ</span></td>
<td class=dense>Can change other users' jobs</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_PRINQ</span></td>
<td class=dense>Can move to printer queue</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_HALTGO</span></td>
<td class=dense>Can halt, restart printer</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_ANYPRIO</span></td>
<td class=dense>Can set any priority on queue</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_CDEFLT</span></td>
<td class=dense>Can change own default priority</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_ADDDEL</span></td>
<td class=dense>Can add/delete printers</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_COVER</span></td>
<td class=dense>Can override class</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_UNQUEUE</span></td>
<td class=dense>Can unqueue jobs</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_VOTHERJ</span></td>
<td class=dense>Can view other jobs not neccesarily edit</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_REMOTEJ</span></td>
<td class=dense>Can access remote jobs</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_REMOTEP</span></td>
<td class=dense>Can access remote printers</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_FREEZEOK</span></td>
<td class=dense>Can save default options</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_ACCESSOK</span></td>
<td class=dense>Can access sub-screens</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_OTHERP</span></td>
<td class=dense>Can use other printers from default</td>
</tr>
<tr>
<td class=dense><span class=FileName>ALLPRIVS</span></td>
<td class=dense>A combination of all of the above</td>
</tr>
</table>
</div>

=for man
.Ip "PV_ADMIN" 8
Administrator (edit admin file)
.Ip "PV_SSTOP" 8
Can run sstop (can stop scheduler)
.Ip "PV_FORMS" 8
Can use other forms than default
.Ip "PV_CPRIO" 8
Can change priority on queue
.Ip "PV_OTHERJ" 8
Can change other users' jobs
.Ip "PV_PRINQ" 8
Can move to printer queue
.Ip "PV_HALTGO" 8
Can halt, restart printer
.Ip "PV_ANYPRIO" 8
Can set any priority on queue
.Ip "PV_CDEFLT" 8
Can change own default priority
.Ip "PV_ADDDEL" 8
Can add/delete printers
.Ip "PV_COVER" 8
Can override class
.Ip "PV_UNQUEUE" 8
Can unqueue jobs
.Ip "PV_VOTHERJ" 8
Can view other jobs not neccesarily edit
.Ip "PV_REMOTEJ" 8
Can access remote jobs
.Ip "PV_REMOTEP" 8
Can access remote printers
.Ip "PV_FREEZEOK" 8
Can save default options
.Ip "PV_ACCESSOK" 8
Can access sub-screens
.Ip "PV_OTHERP" 8
Can use other printers from default
.IP "ALLPRIVS" 8
A combination of all of the above

=head1 RETURN VALUES

=for html
<P>The function returns 0 if successful otherwise one of the error codes
<A HREF="TxtAPI-3.html#Error_codes">listed in Chapter 3</A>.</P>

=for man
The function \fBgspool_getspd()\fR returns 0 if successful otherwise one
of the following codes:

=for man
.Ip "GSPOOL_UNKNOWN_USER" 8
Invalid user name
.Ip "GSPOOL_INVALID_FD" 8
Invalid File descriptor
.Ip "GSPOOL_BADWRITE" 8
failure writing to the network
.Ip "GSPOOL_BADREAD" 8
failure reading from the network
.Ip "GSPOOL_NOPERM" 8
The user does not have permission

=head1 EXAMPLE

An example to view the default privleges on the host machine:

 int fd, ret;
 struct apisphdr res;

 fd = gspool_open("myhost", (char *) 0, 0);
 if (fd < 0) { /* error handling */
     ...
 }

 ret = gspool_getspd(fd, &res);
 if (ret < 0)  { /* error handling */
     ...
 }

 if (res.sph_flgs & PV_HALTGO)
     printf("users cannot stop and start printers\n");

 printf("the default maximum priority is %s\n", res);
 gspool_close(fd);

=head1 SEE ALSO

gspool_getspu(3),
gspool_putspu(3),
gspool_putspd(3).

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

## Local Variables:
## mode: nroff
## End:
