1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.77C-CCK-MCD Caldera Systems OpenLinux [en] (X11; U; Linux 2.4.2 i686) [Netscape]">
<title>OpenSLP Programmers Guide - SLPOpen</title>
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000EF" vlink="#51188E" alink="#FF0000">
<h2>
SLPOpen</h2>
<hr WIDTH="100%">
<h3>
Include</h3>
<h3>
Declaration</h3>
<tt>#include <slp.h></tt>
<p><tt><a href="SLPError.html">SLPError</a> SLPOpen(const char* <a href="#lang">lang</a>,
<a href="SLPTypes.html#SLPBoolean">SLPBoolean</a>
<a href="#isasync">isasync</a>,
<a href="SLPTypes.html#SLPHandle">SLPHandle</a>*
<a href="#phslp">phslp</a>)</tt>
<br>
<h3>
Description</h3>
Returns a <tt>SLPHandle</tt> handle in the <tt>phslp</tt> parameter for
the language locale passed in as the <tt>lang</tt> parameter. The client
indicates if operations on the handle are to be synchronous or asynchronous
through the <tt>isasync</tt> parameter. The handle encapsulates the language
locale for SLP requests issued through the handle, and any other resources
required by the implementation. The return value of the function is an
<tt>SLPError</tt>
code indicating the status of the operation. Upon failure, the <tt>phslp</tt>
parameter is NULL.
<p>An <tt>SLPHandle</tt> can only be used for one SLP API operation at
a time. If the original operation was started asynchronously, any attempt
to start an additional operation on the handle while the original operation
is pending results in the return of an <tt>SLP_HANDLE_IN_USE</tt> error
from the API function. The <tt>SLPClose()</tt> API function terminates
any outstanding calls on the handle. If an implementation is unable to
support a asynchronous( resp. synchronous) operation, due to memory constraints
or lack of threading support, the <tt>SLP_NOT_IMPLEMENTED </tt>flag may
be returned when the isasync flag is <tt>SLP_TRUE</tt> (resp. <tt>SLP_FALSE</tt>).
<p>In the OpenSLP implementation, SLPHandles are used to cache information
that is costly to obtain (in terms of network usage and time).
Since the RFC 2614 API does not specify functions to initialize the
implementation library, OpenSLP keeps track of the number of SLPHandles
that are open. Several global library data structures are initialized
when the first SLPHandle is opened and maintained until the last SLPHandle
is closed. Therefore, it is most efficient to leave SLPHandles open
for as long as you will need them (often for the entire life of a process).
If you can help it, DO NOT make a habit of opening and closing SLPHandles
frequently.
<h3>
Parameters</h3>
<table BORDER CELLPADDING=5 NOSAVE >
<tr VALIGN=TOP NOSAVE>
<td NOSAVE><a NAME="lang"></a><tt>lang</tt></td>
<td NOSAVE>A pointer to null terminated array of characters containing
the RFC 1766 Language Tag for the natural language locale of requests and
registrations issued on the handle. Pass in NULL or the empty string,
"" to use the local the machine is configured to use.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td><a NAME="isasync"></a><tt>isasync</tt></td>
<td NOSAVE>A <tt>SLPBoolean</tt> value indicating whether the <tt>SLPHandle</tt>
should be opened for asynchronous operation or not.</td>
</tr>
<tr VALIGN=TOP NOSAVE>
<td><a NAME="phslp"></a><tt>phslp</tt></td>
<td NOSAVE>A pointer to an <tt>SLPHandle</tt>, in which the open <tt>SLPHandle</tt>
is returned. If an error occurs, the value upon return is NULL.</td>
</tr>
</table>
<h3>
Returns</h3>
<table BORDER NOSAVE >
<tr>
<td>SLP_AUTHENTICATION_FAILED</td>
<td>If the SLP framework supports authentication, this error arises when
a authentication on an SLP message failed.</td>
</tr>
<tr>
<td>SLP_MEMORY_ALLOC_FAILED </td>
<td>Out of memory error</td>
</tr>
<tr>
<td>SLP_PARAMETER_BAD</td>
<td>If a parameter passed into a function is bad, this error is returned.</td>
</tr>
<tr>
<td>SLP_INTERNAL_SYSTEM_ERROR</td>
<td>A basic failure of the API causes this error to be returned. This occurs
when a system call or library fails. The operation could not recover.</td>
</tr>
<tr>
<td>SLP_HANDLE_IN_USE</td>
<td>Callback functions are not permitted to recursively call into the API
on the same SLPHandle, either directly or indirectly. If an attempt is
made to do so, this error is returned from the called API function.</td>
</tr>
</table>
<p>Be aware, especially if the call is async, of error codes that may be
passed to the SLPRegReport() callback function.
<br>
<h3>
Status</h3>
<table CELLPADDING=5 NOSAVE >
<tr VALIGN=TOP NOSAVE>
<td NOSAVE>OpenSLP 0.6.0</td>
<td NOSAVE>Fully implemented as specified by RFC 2614</td>
</tr>
</table>
<h3>
See Also</h3>
<a href="SLPClose.html">SLPClose()</a>
<br>
</body>
</html>
|
