xref: /illumos-gate/usr/src/lib/libslp/clib/slp.h (revision 1da57d55)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License, Version 1.0 only
6  * (the "License").  You may not use this file except in compliance
7  * with the License.
8  *
9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10  * or http://www.opensolaris.org/os/licensing.
11  * See the License for the specific language governing permissions
12  * and limitations under the License.
13  *
14  * When distributing Covered Code, include this CDDL HEADER in each
15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16  * If applicable, add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your own identifying
18  * information: Portions Copyright [yyyy] [name of copyright owner]
19  *
20  * CDDL HEADER END
21  */
22 /*
23  * Copyright (c) 1999 by Sun Microsystems, Inc.
24  * All rights reserved.
25  */
26 
27 #ifndef	_SLP_H
28 #define	_SLP_H
29 
30 /*
31  * This file contains definitions for the Service Location Protocol
32  * C API bindings. More detailed descriptions can be found in the
33  * slp_api(3n) man page.
34  */
35 
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
39 
40 /*
41  * The SLPURLLifetime enum contains URL lifetime values, in seconds,
42  * that are frequently used. If a service is registered with a lifetime
43  * of SLP_LIFETIME_MAXIMUM, the registration will be effectively
44  * permanent, never aging out as long as the SA process is alive.
45  */
46 typedef enum {
47 	SLP_LIFETIME_DEFAULT = 10800,
48 	SLP_LIFETIME_MAXIMUM = 65535
49 } SLPURLLifetime;
50 
51 /*
52  *   The SLPBoolean enum is used as a boolean flag.
53  */
54 typedef enum {
55 	SLP_FALSE = 0,
56 	SLP_TRUE = 1
57 } SLPBoolean;
58 
59 /*
60  *   The SLPSrvURL structure is filled in by the SLPParseSrvURL() function
61  *   with information parsed from a character buffer containing URL.
62  *   The fields correspond to different parts of the URL. Note that
63  *   the structure is conformant with the standard Berkeley sockets
64  *   struct servent, with the exception that the pointer to an array of
65  *   characters for aliases (s_aliases field) is replaced by the pointer
66  *   to host name (s_pcHost field).
67  */
68 typedef struct srvurl {
69 	char	*s_pcSrvType;	/* service type name */
70 	char	*s_pcHost;	/* host identification information */
71 	int	s_iPort;	/* port number, or zero if none */
72 	char	*s_pcNetFamily;	/* network address family identifier */
73 	char	*s_pcSrvPart;	/* remainder of the URL */
74 } SLPSrvURL;
75 
76 /*
77  *   The SLPHandle type is returned by SLPOpen() and is a parameter to all
78  *   SLP functions.  It serves as a handle for all resources allocated on
79  *   behalf of the process by the SLP library.  The type is opaque, since
80  *   the exact nature differs depending on the implementation.
81  */
82 typedef void* SLPHandle;
83 
84 /*
85  *   The SLPError enum contains error codes that are returned from API
86  *   functions.
87  */
88 typedef enum {
89 	SLP_LAST_CALL			= 1,
90 	SLP_OK				= 0,
91 	SLP_LANGUAGE_NOT_SUPPORTED	= -1,
92 	SLP_PARSE_ERROR			= -2,
93 	SLP_INVALID_REGISTRATION	= -3,
94 	SLP_SCOPE_NOT_SUPPORTED		= -4,
95 	SLP_AUTHENTICATION_ABSENT	= -6,
96 	SLP_AUTHENTICATION_FAILED	= -7,
97 	SLP_INVALID_UPDATE		= -13,
98 	SLP_NOT_IMPLEMENTED		= -17,
99 	SLP_BUFFER_OVERFLOW		= -18,
100 	SLP_NETWORK_TIMED_OUT		= -19,
101 	SLP_NETWORK_INIT_FAILED		= -20,
102 	SLP_MEMORY_ALLOC_FAILED		= -21,
103 	SLP_PARAMETER_BAD		= -22,
104 	SLP_NETWORK_ERROR		= -23,
105 	SLP_INTERNAL_SYSTEM_ERROR	= -24,
106 	SLP_HANDLE_IN_USE		= -25,
107 	SLP_TYPE_ERROR			= -26,
108 	SLP_SECURITY_UNAVAILABLE	= -128
109 } SLPError;
110 
111 /*
112  *   The SLPRegReport callback type is the type of the callback function
113  *   to the SLPReg(), SLPDereg(), and SLPDelAttrs() functions.
114  */
115 typedef void
116 SLPRegReport(
117 	SLPHandle	hSLP,		/* operation SLPHandle */
118 	SLPError	errCode,	/* error code */
119 	void		*pvCookie	/* client code cookie */
120 );
121 
122 /*
123  *   The SLPSrvTypeCallback type is the type of the callback function
124  *   parameter to SLPFindSrvTypes() function.
125  */
126 typedef SLPBoolean
127 SLPSrvTypeCallback(
128 	SLPHandle	hSLP,		/* operation SLPHandle */
129 	const char	*pcSrvTypes,	/* list of service types */
130 	SLPError	errCode,	/* error code */
131 	void		*pvCookie	/* client code cookie */
132 );
133 
134 /*
135  *   The SLPSrvURLCallback type is the type of the callback function
136  *   parameter to SLPFindSrvs() function.  The client should return a
137  */
138 typedef SLPBoolean
139 SLPSrvURLCallback(
140 	SLPHandle	hSLP,		/* operation SLPHandle */
141 	const char	*pcSrvURL,	/* the returned service URL */
142 	unsigned short	usLifetime,	/* life time of the service advert */
143 	SLPError	errCode,	/* error code */
144 	void		*pvCookie	/* client code cookie */
145 );
146 
147 /*
148  *   The SLPAttrCallback type is the type of the callback function
149  *   parameter to SLPFindAttrs() function.
150  */
151 typedef SLPBoolean
152 SLPAttrCallback(
153 	SLPHandle	hSLP,		/* operation SLPHandle */
154 	const char	*pcAttrList,	/* attribute id/value assignments */
155 	SLPError	errCode,	/* error code */
156 	void		*pvCookie	/* client code cookie */
157 );
158 
159 extern SLPError
160 SLPOpen(
161 	const char	*pcLang,	/* natural language locale */
162 	SLPBoolean	isAsync,	/* asynchronous if true */
163 	SLPHandle	*phSLP		/* pointer to resulting handle */
164 );
165 
166 /*
167  * Frees all resources associated with the handle
168  */
169 extern void SLPClose(
170 	SLPHandle	hSLP		/* handle to be closed */
171 );
172 
173 /*
174  *   Registers the URL in pcSrvURL having the lifetime usLifetime with the
175  *   attribute list in pcAttrs.
176  */
177 extern SLPError
178 SLPReg(
179 	SLPHandle	hSLP,		/* operation SLPHandle */
180 	const char	*pcSrvURL,	/* the URL to register */
181 	const unsigned short usLifetime, /* life time of the service advert */
182 	const char	*pcSrvType,	/* the service type */
183 	const char	*pcAttrs,	/* attributes of the advertisement */
184 	SLPBoolean	fresh,		/* fresh registration if true */
185 	SLPRegReport	callback,	/* receives completion status */
186 	void		*pvCookie	/* client code cookie */
187 );
188 
189 /*
190  *   Deregisters the advertisment for URL pURL in all scopes where the
191  *   service is registered and all language locales, not just the locale
192  *   of the SLPHandle.
193  */
194 extern SLPError
195 SLPDereg(
196 	SLPHandle	hSLP,		/* operation SLPHandle */
197 	const char	*pcURL,		/* the URL to deregister */
198 	SLPRegReport	callback,	/* receives completion status */
199 	void		*pvCookie	/* client code cookie */
200 );
201 
202 /*
203  *   Delete the selected attributes in the locale of the SLPHandle.
204  */
205 extern SLPError
206 SLPDelAttrs(
207 	SLPHandle	hSLP,		/* operation SLPHandle */
208 	const char	*pcURL,		/* URL for attrs to deregister */
209 	const char	*pcAttrs,	/* attributes to deregister */
210 	SLPRegReport	callback,	/* receives completion status */
211 	void		*pvCookie	/* client code cookie */
212 );
213 
214 /*
215  *   The SLPFindSrvType() function issues an SLP service type request
216  *   for service types in the scopes indicated by the pcScopeList.  The
217  *   results are returned through the callback parameter.
218  */
219 extern SLPError
220 SLPFindSrvTypes(
221 	SLPHandle	hSLP,		/* operation SLPHandle */
222 	const char	*pcNamingAuthority, /* naming authority to search */
223 	const char	*pcScopeList,	/* scopes to search */
224 	SLPSrvTypeCallback callback,	/* receives results */
225 	void		*pvCookie	/* client code cookie */
226 );
227 
228 /*
229  *   Issue the query for services on the language specific SLPHandle and
230  *   return the results through the callback.
231  */
232 extern SLPError
233 SLPFindSrvs(
234 	SLPHandle	hSLP,		/* operation SLPHandle */
235 	const char	*pcServiceType,	/* service type string */
236 	const char	*pcScopeList,	/* scopes to search */
237 	const char	*pcSearchFilter, /* LDAPv3 Search Filter */
238 	SLPSrvURLCallback callback,	/* receives results */
239 	void		*pvCookie	/* client code cookie */
240 );
241 
242 /*
243  *   This function returns service attributes matching the attribute ids
244  *   for the indicated full or partial URL.
245  */
246 extern SLPError
247 SLPFindAttrs(
248 	SLPHandle	hSLP,		/* operation SLPHandle */
249 	const char	*pcURL,		/* the full or partial URL */
250 	const char	*pcScopeList,	/* scopes to search */
251 	const char	*pcAttrIds,	/* which attribute values to return */
252 	SLPAttrCallback	callback,	/* receives results */
253 	void		*pvCookie	/* client code cookie */
254 );
255 
256 /*
257  *   Returns the minimum refresh interval, in seconds, that any SA
258  *   should use when refreshing registrations. If 0, there is no
259  *   minimum interval, and the SA can use what it pleases.
260  */
261 extern unsigned short
262 SLPGetRefreshInterval();
263 
264 /*
265  *   Sets ppcScopeList parameter to a pointer to a comma separated list
266  *   including all available scope values.
267  */
268 extern SLPError
269 SLPFindScopes(
270 	SLPHandle	hSLP,		/* operation SLPHandle */
271 	char		**ppcScopeList	/* pointer to result */
272 );
273 
274 /*
275  *   Parses the URL passed in as the argument into a service URL structure
276  *   and return it in the ppSrvURL pointer.
277  */
278 extern SLPError
279 SLPParseSrvURL(
280 	char		*pcSrvURL,	/* URL string to parse */
281 	SLPSrvURL	**ppSrvURL	/* pointer to result */
282 );
283 
284 /*
285  *   Frees memory returned from SLPParseSrvURL(), SLPEscape(),
286  *   SLPUnescape(), and SLPFindScopes().
287  */
288 extern void
289 SLPFree(
290 	void	*pvMem			/* pointer to memory to free */
291 );
292 
293 /*
294  *   Process the input string in pcInbuf and escape any SLP reserved
295  *   characters.
296  */
297 extern SLPError
298 SLPEscape(
299 	const char	*pcInbuf,	/* buffer to process */
300 	char		**ppcOutBuf,	/* pointer to result */
301 	SLPBoolean	isTag		/* if true, check for bad tag chars */
302 );
303 
304 /*
305  *   Process the input string in pcInbuf and unescape any SLP reserved
306  *   characters.
307  */
308 extern SLPError
309 SLPUnescape(
310 	const char	*pcInbuf,	/* buffer to process */
311 	char		**ppcOutbuf,	/* pointer to result */
312 	SLPBoolean	isTag		/* if true, check for bad tag chars */
313 );
314 
315 /*
316  *   Returns the value of the corresponding SLP property name.  The
317  *   returned string is owned by the library and MUST NOT be freed.
318  */
319 extern const char *
320 SLPGetProperty(
321 	const char	*pcName		/* property name */
322 );
323 
324 /*
325  *   Sets the value of the SLP property to the new value.  The pcValue
326  *   parameter should be the property value as a string.
327  */
328 extern void
329 SLPSetProperty(
330 	const char	*pcName,	/* property name */
331 	const char	*pcValue	/* property value */
332 );
333 
334 /*
335  * Maps err_code to an SLP error string. The returned string should not
336  * be overwritten.
337  */
338 extern const char *
339 slp_strerror(
340 	SLPError err_code		/* SLP error code */
341 );
342 
343 #ifdef __cplusplus
344 }
345 #endif
346 
347 #endif	/* _SLP_H */
348