1papiServiceCreate(3PAPI)    PAPI Library Functions    papiServiceCreate(3PAPI)
2
3
4

NAME

6       papiServiceCreate, papiServiceDestroy, papiServiceSetUserName, papiSer‐
7       viceSetPassword, papiServiceSetEncryption, papiServiceSetAuthCB, papiS‐
8       erviceSetAppData,   papiServiceGetServiceName,  papiServiceGetUserName,
9       papiServiceGetPassword,  papiServiceGetEncryption,   papiServiceGetApp‐
10       Data,  papiServiceGetAttributeList,  papiServiceGetStatusMessage - ser‐
11       vice context manipulation
12

SYNOPSIS

14       cc [ flag... ] file... -lpapi [ library... ]
15       #include <papi.h>
16
17       papi_status_t papiServiceCreate(papi_service_t *handle,
18            char *service_name, char *user_name, char *password,
19            int (*authCB)(papi_service_t svc, void *app_data),
20            papi_encryption_t encryption, void *app_data);
21
22
23       void papiServiceDestroy(papi_service_t handle);
24
25
26       papi_status_t papiServiceSetUserName(papi_service_t handle,
27            char *user_name);
28
29
30       papi_status_t papiServiceSetPassword(papi_service_t handle,
31            char *password);
32
33
34       papi_status_t papiServiceSetEncryption(papi_service_t handle,
35            papi_encryption_t encryption);
36
37
38       papi_status_t papiServiceSetAuthCB(papi_service_t handle,
39            int (*authCB)(papi_service_t s, void *app_data));
40
41
42       papi_status_t papiServiceSetAppData(papi_service_t handle,
43            void *app_data);
44
45
46       char *papiServiceGetServiceName(papi_service_t handle);
47
48
49       char *papiServiceGetUserName(papi_service_t handle);
50
51
52       char *papiServiceGetPassword(papi_service_t handle);
53
54
55       papi_encryption_t papiServiceGetEncryption(papi_service_t handle);
56
57
58       void *papiServiceGetAppData(papi_service_t handle);
59
60
61       papi_attribute_t **papiServiceGetAttributeList(papi_service_t handle);
62
63
64       char *papiServiceGetStatusMessage(papi_service_t handle);
65
66

PARAMETERS

68       app_data        a set of additional data to be  passed  to  the  authCB
69                       if/when it is called
70
71
72       authCB          a callback routine use to gather additional authentica‐
73                       tion information on behalf of the print service
74
75
76       encryption      whether or not encryption should be used for communica‐
77                       tion  with  the  print  service,  where  applicable. If
78                       PAPI_ENCRYPT_IF_REQUESTED is specified, encryption will
79                       be   used   if  the  print  service  requests  it.   If
80                       PAPI_ENCRYPT_NEVER is specified, encryption will not be
81                       used  while  communicating  with the print service.  If
82                       PAPI_ENCRYPT_REQUIRED or PAPI_ENCRYPT_ALWAYS is  speci‐
83                       fied,  encryption  will be required while communicating
84                       with the print service
85
86
87       handle          a pointer to a handle to be used for all libpapi opera‐
88                       tions.  This handle should be initialized to NULL prior
89                       to creation
90
91
92       password        a plain text password to be used  during  any  required
93                       user authentication with the print service function set
94                       with papiServiceSetAuthCB(). This provides the callback
95                       function  a  means of interrogating the service context
96                       for user information and setting a password.
97
98
99       s               the service context passed into the the  authentication
100                       callback
101
102
103       service_name    the  name  of  a print service to contact.  This can be
104                       NULL, a print service name like "lpsched", a resolvable
105                       printer name, or a printer-uri like ipp://server/print‐
106                       ers/queue.
107
108
109       svc             a handle (service  context)  used  by  subsequent  PAPI
110                       calls  to  keep/pass  information across PAPI calls. It
111                       generally contains connection, state,  and  authentica‐
112                       tion information.
113
114
115       user_name       the name of the user to act on behalf of while contact‐
116                       ing the print service.  If a value of NULL is used, the
117                       user  name  associated  with  the current processes UID
118                       will be used. Specifying a user name might require fur‐
119                       ther authentication with the print service.
120
121

DESCRIPTION

123       The  papiServiceCreate()  function creates a service context for use in
124       subsequent calls to libpapi functions.  The context is returned in  the
125       handle  argument.  This  context must be destroyed using papiServiceDe‐
126       stroy() even if the papiServiceCreate() call failed.
127
128
129       The papiServiceSet*() functions modifies the  requested  value  in  the
130       service  context  passed in.  It is recommended that these functions be
131       avoided in favor of supplying the information when the context is  cre‐
132       ated.
133
134
135       The  papiServiceGetStatusMessage()  function retrieves a detailed error
136       message associated with the service context.  This message  will  apply
137       to the last failed operation.
138
139
140       The remaining papiServiceGet*() functions return the requested informa‐
141       tion associated with the service context.  A value  of  NULL  indicates
142       that the requested value was not initialized or is unavailable.
143

RETURN VALUES

145       Upon  successful  completion,  papiServiceCreate() and the papiService‐
146       Set*() functions return PAPI_OK. Otherwise, they return an  appropriate
147       papi_status_t indicating the type of failure.
148
149
150       Upon  successful  completion,  the papiServiceGet*() functions return a
151       pointer to the requested data. Otherwise, they return NULL.
152

EXAMPLES

154       Example 1 Create a PAPI service context.
155
156         /*
157          * program to create a PAPI service context.
158          */
159         #include <stdio.h>
160         #include <papi.h>
161
162         static int
163         authCB(papi_service_t svc, void *app_data)
164         {
165             char prompt[BUFSIZ];
166             char *user, *svc_name, *passphrase;
167
168             /* get the name of the service we are contacting */
169             if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
170                     return (-1);
171
172             /* find out who we are supposed to be */
173             if ((user = papiServiceGetUserName(svc)) == NULL) {
174                     struct passwd *pw;
175
176                     if ((pw = getpwuid(getuid())) != NULL)
177                             user = pw->pw_name;
178                     else
179                             user = "nobody";
180             }
181
182             /* build the prompt string */
183             snprintf(prompt, sizeof (prompt),
184                     gettext("passphrase for %s to access %s: "), user,
185                           svc_name);
186
187             /* ask for the passphrase */
188             if ((passphrase = getpassphrase(prompt)) != NULL)
189                     papiServiceSetPassword(svc, passphrase);
190
191             return (0);
192         }
193
194         /*ARGSUSED*/
195         int
196         main(int ac, char *av[])
197         {
198             char buf[BUFSIZ];
199             papi_status_t status;
200             papi_service_t *svc = NULL;
201
202             status = papiServiceCreate(&svc, av[1], NULL, NULL, authCB,
203                                     PAPI_ENCRYPT_NEVER, NULL);
204
205             if (status != PAPI_OK) {
206                 /* do something */
207             } else
208                 printf("Failed(%s): %s: %s\n", av[1], papiStatusString(status),
209                         papiStatusMessage(svc));
210
211             papiServiceDestroy(svc);
212         }
213
214

ATTRIBUTES

216       See attributes(5) for descriptions of the following attributes:
217
218
219
220
221       ┌─────────────────────────────┬─────────────────────────────┐
222       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
223       ├─────────────────────────────┼─────────────────────────────┤
224       │Interface Stability          │Volatile                     │
225       ├─────────────────────────────┼─────────────────────────────┤
226       │MT-Level                     │Safe                         │
227       └─────────────────────────────┴─────────────────────────────┘
228

SEE ALSO

230       libpapi(3LIB), attributes(5)
231
232
233
234SunOS 5.11                        17 Jan 2007         papiServiceCreate(3PAPI)
Impressum