OpenSLP Programmers Guide - SLPOpen

About
what is openslp

Download
how to get openslp

Contribute
how to help out

Documentation
how to find out more

Credits
who to blame

## SLPOpen
OpenSLP Programmer's Guide » SLP Handle Functions » SLPOpen

### Declaration

    #include <slp.h>

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

### Description

Returns an `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, except for asynchronous operation.

### See Also

SLPClose

Prepared by: Caldera Systems Inc
Maintained by: openslp.org