te
Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
papiServiceCreate, papiServiceDestroy, papiServiceSetUserName, papiServiceSetPassword, papiServiceSetEncryption, papiServiceSetAuthCB, papiServiceSetAppData, papiServiceGetServiceName, papiServiceGetUserName, papiServiceGetPassword, papiServiceGetEncryption, papiServiceGetAppData, papiServiceGetAttributeList, papiServiceGetStatusMessage - service context manipulation

cc [ flag.\|.\|. ] file.\|.\|. -lpapi [ library.\|.\|. ] 
#include <papi.h>

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);

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);

app_data

authCB

encryption

handle

password

s

service_name

svc

user_name

The papiServiceCreate() function creates a service context for use in subsequent calls to libpapi functions. The context is returned in the handle argument. This context must be destroyed using papiServiceDestroy() even if the papiServiceCreate() 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 information 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.

Upon successful completion, papiServiceCreate() and the papiServiceSet*() functions return PAPI_OK. Otherwise, they return an appropriate papi_status_t indicating the type of failure.

Upon successful completion, the papiServiceGet*() functions return a pointer to the requested data. Otherwise, they return NULL.

Example 1 Create a PAPI service context.

/*
 * program to create a PAPI service context.
 */
#include <stdio.h>
#include <papi.h>

static int
authCB(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;

 status = papiServiceCreate(&svc, av[1], NULL, NULL, authCB,
 PAPI_ENCRYPT_NEVER, NULL);

 if (status != PAPI_OK) {
 /* do something */
 } else
 printf("Failed(%s): %s: %s\en", av[1], papiStatusString(status),
 papiStatusMessage(svc));

 papiServiceDestroy(svc);
}

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Volatile
MT-Level	Safe

libpapi(3LIB), attributes(5)