OpenSLP Programmers Guide

SLPOpen

Include

Declaration

#include <slp.h>

SLPError SLPOpen(const char* lang, SLPBoolean isasync, SLPHandle* phslp)

Description

Returns a SLPHandle handle in the phslp parameter for the language locale passed in as the lang parameter. The client indicates if operations on the handle are to be synchronous or asynchronous through the isasync 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 SLPError code indicating the status of the operation. Upon failure, the phslp parameter is NULL.

An SLPHandle 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 SLP_HANDLE_IN_USE error from the API function. The SLPClose() 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 SLP_NOT_IMPLEMENTED flag may be returned when the isasync flag is SLP_TRUE (resp. SLP_FALSE).

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.

Parameters

`lang`	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.
`isasync`	A `SLPBoolean` value indicating whether the `SLPHandle` should be opened for asynchronous operation or not.
`phslp`	A pointer to an `SLPHandle`, in which the open `SLPHandle` is returned. If an error occurs, the value upon return is NULL.

Returns

SLP_AUTHENTICATION_FAILED	If the SLP framework supports authentication, this error arises when a authentication on an SLP message failed.
SLP_MEMORY_ALLOC_FAILED	Out of memory error
SLP_PARAMETER_BAD	If a parameter passed into a function is bad, this error is returned.
SLP_INTERNAL_SYSTEM_ERROR	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.
SLP_HANDLE_IN_USE	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.

Be aware, especially if the call is async, of error codes that may be passed to the SLPRegReport() callback function.

Status

OpenSLP 0.6.0

Fully implemented as specified by RFC 2614