PAPI Library Functions papiServiceCreate(3PAPI)
NAME
papiServiceCreate, papiServiceDestroy, papiServiceSetUser-
Name, papiServiceSetPassword, papiServiceSetEncryption, pap-
iServiceSetAuthCB, papiServiceSetAppData, papiServiceGetSer-
viceName, papiServiceGetUserName, papiServiceGetPassword,
papiServiceGetEncryption, papiServiceGetAppData, papiServi-
ceGetAttributeList, papiServiceGetStatusMessage - service
context manipulation
SYNOPSIS
cc [ flag... ] file... -lpapi [ library... ]
#include
papistatust papiServiceCreate(papiservicet *handle,
char *servicename, char *username, char *password,
int (*authCB)(papiservicet svc, void *appdata),
papiencryptiont encryption, void *appdata);
void papiServiceDestroy(papiservicet handle);
papistatust papiServiceSetUserName(papiservicet handle,
char *username);
papistatust papiServiceSetPassword(papiservicet handle,
char *password);
papistatust papiServiceSetEncryption(papiservicet handle,
papiencryptiont encryption);
papistatust papiServiceSetAuthCB(papiservicet handle,
int (*authCB)(papiservicet s, void *appdata));
papistatust papiServiceSetAppData(papiservicet handle,
void *appdata);
char *papiServiceGetServiceName(papiservicet handle);
char *papiServiceGetUserName(papiservicet handle);
char *papiServiceGetPassword(papiservicet handle);
SunOS 5.11 Last change: 17 Jan 2007 1
PAPI Library Functions papiServiceCreate(3PAPI)
papiencryptiont papiServiceGetEncryption(papiservicet handle);
void *papiServiceGetAppData(papiservicet handle);
papiattributet **papiServiceGetAttributeList(papiservicet handle);
char *papiServiceGetStatusMessage(papiservicet handle);
PARAMETERS
appdata a set of additional data to be passed to the
authCB if/when it is called
authCB a callback routine use to gather additional
authentication information on behalf of the
print service
encryption whether or not encryption should be used for
communication with the print service, where
applicable. If PAPIENCRYPTIFREQUESTED is
specified, encryption will be used if the
print service requests it. If
PAPIENCRYPTNEVER is specified, encryption
will not be used while communicating with
the print service. If PAPIENCRYPTREQUIRED
or PAPIENCRYPTALWAYS is specified, encryp-
tion will be required while communicating
with the print service
handle a pointer to a handle to be used for all
libpapi operations. This handle should be
initialized to NUL prior to creation
password a plain text password to be used during any
required user authentication with the print
service function set with papiServi-
ceSetAuthCB(). This provides the callback
function a means of interrogating the ser-
vice context for user information and set-
ting a password.
s the service context passed into the the
authentication callback
SunOS 5.11 Last change: 17 Jan 2007 2
PAPI Library Functions papiServiceCreate(3PAPI)
servicename the name of a print service to contact.
This can be NUL, a print service name like
"lpsched", a resolvable printer name, or a
printer-uri like
ipp:/server/printers/queue.
svc a handle (service context) used by subse-
quent PAPI calls to keep/pass information
across PAPI calls. It generally contains
connection, state, and authentication infor-
mation.
username the name of the user to act on behalf of
while contacting the print service. If a
value of NUL is used, the user name associ-
ated with the current processes UID will be
used. Specifying a user name might require
further authentication with the print ser-
vice.
DESCRIPTION
The papiServiceCreate() function creates a service context
for use in subsequent calls to libpapi functions. The con-
text is returned in the handle argument. This context must
be destroyed using papiServiceDestroy() even if the papiSer-
viceCreate() call failed.
The papiServiceSet*() functions modifies the requested value
in the service context passed in. It is recommended that
these functions be avoided in favor of supplying the infor-
mation when the context is created.
The papiServiceGetStatusMessage() function retrieves a
detailed error message associated with the service context.
This message will apply to the last failed operation.
The remaining papiServiceGet*() functions return the
requested information associated with the service context.
A value of NUL indicates that the requested value was not
initialized or is unavailable.
RETURN VALUES
Upon successful completion, papiServiceCreate() and the pap-
iServiceSet*() functions return PAPIOK. Otherwise, they
return an appropriate papistatust indicating the type of
failure.
SunOS 5.11 Last change: 17 Jan 2007 3
PAPI Library Functions papiServiceCreate(3PAPI)
Upon successful completion, the papiServiceGet*() functions
return a pointer to the requested data. Otherwise, they
return NUL.
EXAMPLES
Example 1 Create a PAPI service context.
/*
* program to create a PAPI service context.
*/
#include
#include
static int
authCB(papiservicet svc, void *appdata)
{
char prompt[BUFSIZ];
char *user, *svcname, *passphrase;
/* get the name of the service we are contacting */
if ((svcname = papiServiceGetServiceName(svc)) == NUL)
return (-1);
/* find out who we are supposed to be */
if ((user = papiServiceGetUserName(svc)) == NUL) {
struct passwd *pw;
if ((pw = getpwuid(getuid())) != NUL)
user = pw->pwname;
else
user = "nobody";
}
/* build the prompt string */
snprintf(prompt, sizeof (prompt),
gettext("passphrase for %s to access %s: "), user,
svcname);
/* ask for the passphrase */
if ((passphrase = getpassphrase(prompt)) != NUL)
papiServiceSetPassword(svc, passphrase);
return (0);
}
/*ARGSUSED*/
int
main(int ac, char *av[])
{
char buf[BUFSIZ];
papistatust status;
papiservicet *svc = NUL;
SunOS 5.11 Last change: 17 Jan 2007 4
PAPI Library Functions papiServiceCreate(3PAPI)
status = papiServiceCreate(&svc, av[1], NUL, NUL, authCB,
PAPIENCRYPTNEVER, NUL);
if (status != PAPIOK) {
/* do something */
} else
printf("Failed(%s): %s: %s\n", av[1], papiStatusString(status),
papiStatusMessage(svc));
papiServiceDestroy(svc);
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Volatile
MT-Level Safe
SEE ALSO
libpapi(3LIB), attributes(5)
SunOS 5.11 Last change: 17 Jan 2007 5
|
