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 manipulationSYNOPSIS
cc [ flag... ] file... -lpapi [ library... ]
#include
papi_status_t papiServiceCreate(papi_service_t *handle,
char *service_name, char *user_name, char *password,
int (*authCB)(papi_service_t svc, void *app_data),
papi_encryption_t encryption, void *app_data);
void papiServiceDestroy(papi_service_t handle);
papi_status_t papiServiceSetUserName(papi_service_t handle,
char *user_name);
papi_status_t papiServiceSetPassword(papi_service_t handle,
char *password);papi_status_t papiServiceSetEncryption(papi_service_t handle,
papi_encryption_t encryption);
papi_status_t papiServiceSetAuthCB(papi_service_t handle,
int (*authCB)(papi_service_t s, void *app_data));
papi_status_t papiServiceSetAppData(papi_service_t handle,
void *app_data);
char *papiServiceGetServiceName(papi_service_t handle);
char *papiServiceGetUserName(papi_service_t handle);
char *papiServiceGetPassword(papi_service_t handle);
SunOS 5.11 Last change: 17 Jan 2007 1
PAPI Library Functions papiServiceCreate(3PAPI)papi_encryption_t papiServiceGetEncryption(papi_service_t handle);
void *papiServiceGetAppData(papi_service_t handle);
papi_attribute_t **papiServiceGetAttributeList(papi_service_t handle);
char *papiServiceGetStatusMessage(papi_service_t handle);
PARAMETERS
app_data 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, whereapplicable. If PAPI_ENCRYPT_IF_REQUESTED is
specified, encryption will be used if the print service requests it. IfPAPI_ENCRYPT_NEVER is specified, encryption
will not be used while communicating withthe print service. If PAPI_ENCRYPT_REQUIRED
or PAPI_ENCRYPT_ALWAYS 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 NULL prior to creation password a plain text password to be used during any required user authentication with the printservice function set with papiServi-
ceSetAuthCB(). This provides the callbackfunction 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 callbackSunOS 5.11 Last change: 17 Jan 2007 2
PAPI Library Functions papiServiceCreate(3PAPI)service_name the name of a print service to contact.
This can be NULL, a print service name like "lpsched", a resolvable printer name, or aprinter-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 containsconnection, state, and authentication infor-
mation.user_name the name of the user to act on behalf of
while contacting the print service. If avalue of NULL is used, the user name associ-
ated with the current processes UID will be used. Specifying a user name might requirefurther authentication with the print ser-
vice.DESCRIPTION
The papiServiceCreate() function creates a service contextfor use in subsequent calls to libpapi functions. The con-
text is returned in the handle argument. This context mustbe 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 thatthese 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 NULL indicates that the requested value was not initialized or is unavailable.RETURN VALUES
Upon successful completion, papiServiceCreate() and the pap-
iServiceSet*() functions return PAPI_OK. Otherwise, they
return an appropriate papi_status_t 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 NULL.EXAMPLES
Example 1 Create a PAPI service context. /* * program to create a PAPI service context. */#include
#include
static intauthCB(papi_service_t svc, void *app_data)
{ char prompt[BUFSIZ];char *user, *svc_name, *passphrase;
/* get the name of the service we are contacting */if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
return (-1);
/* find out who we are supposed to be */ if ((user = papiServiceGetUserName(svc)) == NULL) { struct passwd *pw; if ((pw = getpwuid(getuid())) != NULL)user = pw->pw_name;
else user = "nobody"; } /* build the prompt string */ snprintf(prompt, sizeof (prompt),gettext("passphrase for %s to access %s: "), user,
svc_name);
/* ask for the passphrase */ if ((passphrase = getpassphrase(prompt)) != NULL) papiServiceSetPassword(svc, passphrase); return (0); } /*ARGSUSED*/ int main(int ac, char *av[]) { char buf[BUFSIZ];papi_status_t status;
papi_service_t *svc = NULL;
SunOS 5.11 Last change: 17 Jan 2007 4
PAPI Library Functions papiServiceCreate(3PAPI) status = papiServiceCreate(&svc, av[1], NULL, NULL, authCB,PAPI_ENCRYPT_NEVER, NULL);
if (status != PAPI_OK) {
/* do something */ } elseprintf("Failed(%s): %s: %s\n", av[1], papiStatusString(status),
papiStatusMessage(svc));papiServiceDestroy(svc);
}ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Volatile ||_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
libpapi(3LIB), attributes(5)SunOS 5.11 Last change: 17 Jan 2007 5