1papiServiceCreate(3PAPI) PAPI Library Functions papiServiceCreate(3PAPI)
2
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
14 cc [ flag... ] file... -lpapi [ library... ]
15 #include <papi.h>
16 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 void papiServiceDestroy(papi_service_t handle);
24 papi_status_t papiServiceSetUserName(papi_service_t handle,
27 char *user_name);
28 papi_status_t papiServiceSetPassword(papi_service_t handle,
31 char *password);
32 papi_status_t papiServiceSetEncryption(papi_service_t handle,
35 papi_encryption_t encryption);
36 papi_status_t papiServiceSetAuthCB(papi_service_t handle,
39 int (*authCB)(papi_service_t s, void *app_data));
40 papi_status_t papiServiceSetAppData(papi_service_t handle,
43 void *app_data);
44 char *papiServiceGetServiceName(papi_service_t handle);
47 char *papiServiceGetUserName(papi_service_t handle);
50 char *papiServiceGetPassword(papi_service_t handle);
53 papi_encryption_t papiServiceGetEncryption(papi_service_t handle);
56 void *papiServiceGetAppData(papi_service_t handle);
59 papi_attribute_t **papiServiceGetAttributeList(papi_service_t handle);
62 char *papiServiceGetStatusMessage(papi_service_t handle);
65
68 app_data a set of additional data to be passed to the authCB
69 if/when it is called
70 authCB a callback routine use to gather additional authentica‐
73 tion information on behalf of the print service
74 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 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 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 s the service context passed into the the authentication
100 callback
101 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 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 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
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 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 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 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
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 Upon successful completion, the papiServiceGet*() functions return a
151 pointer to the requested data. Otherwise, they return NULL.
152
154 Example 1 Create a PAPI service context.
155 /*
157 * program to create a PAPI service context.
158 */
159 #include <stdio.h>
160 #include <papi.h>
161 static int
163 authCB(papi_service_t svc, void *app_data)
164 {
165 char prompt[BUFSIZ];
166 char *user, *svc_name, *passphrase;
167 /* get the name of the service we are contacting */
169 if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
170 return (-1);
171 /* find out who we are supposed to be */
173 if ((user = papiServiceGetUserName(svc)) == NULL) {
174 struct passwd *pw;
175 if ((pw = getpwuid(getuid())) != NULL)
177 user = pw->pw_name;
178 else
179 user = "nobody";
180 }
181 /* build the prompt string */
183 snprintf(prompt, sizeof (prompt),
184 gettext("passphrase for %s to access %s: "), user,
185 svc_name);
186 /* ask for the passphrase */
188 if ((passphrase = getpassphrase(prompt)) != NULL)
189 papiServiceSetPassword(svc, passphrase);
190 return (0);
192 }
193 /*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 status = papiServiceCreate(&svc, av[1], NULL, NULL, authCB,
203 PAPI_ENCRYPT_NEVER, NULL);
204 if (status != PAPI_OK) {
206 /* do something */
207 } else
208 printf("Failed(%s): %s: %s\n", av[1], papiStatusString(status),
209 papiStatusMessage(svc));
210 papiServiceDestroy(svc);
212 }
213
216 See attributes(5) for descriptions of the following attributes:
217 ┌─────────────────────────────┬─────────────────────────────┐
222 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
223 ├─────────────────────────────┼─────────────────────────────┤
224 │Interface Stability │Volatile │
225 ├─────────────────────────────┼─────────────────────────────┤
226 │MT-Level │Safe │
227 └─────────────────────────────┴─────────────────────────────┘
228
230 libpapi(3LIB), attributes(5)
231SunOS 5.11 17 Jan 2007 papiServiceCreate(3PAPI)