You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
991 lines
61 KiB
991 lines
61 KiB
/***************************************************************************/
|
|
/* */
|
|
/* Project: OpenSLP - OpenSource implementation of Service Location */
|
|
/* Protocol */
|
|
/* */
|
|
/* File: slp.h */
|
|
/* */
|
|
/* Abstract: Main header file for the SLP API exactly as described by */
|
|
/* rfc2614. This is the only file that needs to be included */
|
|
/* in order make all SLP API declarations. */
|
|
/* */
|
|
/* Author(s) Matt Peterson <mpeterson@caldera.com> */
|
|
/*-------------------------------------------------------------------------*/
|
|
/* */
|
|
/* Please submit patches to http://www.openslp.org */
|
|
/* */
|
|
/*-------------------------------------------------------------------------*/
|
|
/* */
|
|
/* Copyright (C) 2000 Caldera Systems, Inc */
|
|
/* All rights reserved. */
|
|
/* */
|
|
/* Redistribution and use in source and binary forms, with or without */
|
|
/* modification, are permitted provided that the following conditions are */
|
|
/* met: */
|
|
/* */
|
|
/* Redistributions of source code must retain the above copyright */
|
|
/* notice, this list of conditions and the following disclaimer. */
|
|
/* */
|
|
/* Redistributions in binary form must reproduce the above copyright */
|
|
/* notice, this list of conditions and the following disclaimer in */
|
|
/* the documentation and/or other materials provided with the */
|
|
/* distribution. */
|
|
/* */
|
|
/* Neither the name of Caldera Systems nor the names of its */
|
|
/* contributors may be used to endorse or promote products derived */
|
|
/* from this software without specific prior written permission. */
|
|
/* */
|
|
/* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS */
|
|
/* `AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT */
|
|
/* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR */
|
|
/* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE CALDERA */
|
|
/* SYSTEMS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, */
|
|
/* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT */
|
|
/* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, */
|
|
/* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON */
|
|
/* ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT */
|
|
/* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE */
|
|
/* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */
|
|
/* */
|
|
/***************************************************************************/
|
|
|
|
#if(!defined SLP_H_INCLUDED)
|
|
#define SLP_H_INCLUDED
|
|
|
|
#if(defined __cplusplus)
|
|
extern "C"
|
|
{
|
|
#endif
|
|
|
|
#if defined(_WIN32) && defined(_MSC_VER)
|
|
/* MSVC auto-exports, BCB uses .def file */
|
|
# define SLPCALLBACK
|
|
# ifdef LIBSLP_EXPORTS
|
|
# define SLPEXP __declspec(dllexport)
|
|
# elif defined(LIBSLP_STATIC)
|
|
# define SLPEXP
|
|
# else
|
|
# define SLPEXP __declspec(dllimport)
|
|
# endif
|
|
# define SLPAPI
|
|
#else
|
|
# define SLPCALLBACK
|
|
# define SLPEXP
|
|
# define SLPAPI
|
|
#endif
|
|
|
|
/*==========================================================================*/
|
|
/* lifetime values, in seconds, that are frequently used. */
|
|
/*==========================================================================*/
|
|
#define SLP_LIFETIME_DEFAULT 10800 /* 3 hours */
|
|
#define SLP_LIFETIME_MAXIMUM 65535 /* 18 hours */
|
|
|
|
|
|
/*==========================================================================*/
|
|
/* SLPError */
|
|
/* --------- */
|
|
/* The SLPError type represents error codes that are returned from API */
|
|
/* functions. */
|
|
typedef int SLPError;
|
|
|
|
#define SLP_LAST_CALL 1
|
|
|
|
/* passed to callback functions when the API */
|
|
/* library has no more data for them and therefore no further calls */
|
|
/* will be made to the callback on the currently outstanding operation. */
|
|
/* The callback can use this to signal the main body of the client code */
|
|
/* that no more data will be forthcoming on the operation, so that the */
|
|
/* main body of the client code can break out of data collection loops. */
|
|
/* On * the last call of a callback during both a synchronous and */
|
|
/* asynchronous call, the error code parameter has value SLP_LAST_CALL, */
|
|
/* and the other parameters are all NULL. If no results are returned by */
|
|
/* an API operation, then only one call is made, with the error */
|
|
/* parameter set to SLP_LAST_CALL. */
|
|
|
|
#define SLP_OK 0
|
|
|
|
/* indicates that the no error occurred during the operation. */
|
|
|
|
#define SLP_LANGUAGE_NOT_SUPPORTED -1
|
|
|
|
/* No DA or SA has service advertisement or attribute information */
|
|
/* in the language requested, but at least one DA or SA indicated, */
|
|
/* via the LANGUAGE_NOT_SUPPORTED error code, that it might have */
|
|
/* information for that service in another language */
|
|
|
|
#define SLP_PARSE_ERROR -2
|
|
|
|
/* The SLP message was rejected by a remote SLP agent. The API */
|
|
/* returns this error only when no information was retrieved, and */
|
|
/* at least one SA or DA indicated a protocol error. The data */
|
|
/* supplied through the API may be malformed or a may have been */
|
|
/* damaged in transit. */
|
|
|
|
#define SLP_INVALID_REGISTRATION -3
|
|
|
|
/* The API may return this error if an attempt to register a */
|
|
/* service was rejected by all DAs because of a malformed URL or */
|
|
/* attributes. SLP does not return the error if at least one DA */
|
|
/* accepted the registration. */
|
|
|
|
#define SLP_SCOPE_NOT_SUPPORTED -4
|
|
|
|
/* The API returns this error if the SA has been configured with */
|
|
/* net.slp.useScopes value-list of scopes and the SA request did */
|
|
/* not specify one or more of these allowable scopes, and no */
|
|
/* others. It may be returned by a DA or SA if the scope included */
|
|
/* in a request is not supported by the DA or SA. */
|
|
|
|
#define SLP_AUTHENTICATION_ABSENT -6
|
|
|
|
/* if the SLP framework supports authentication, this error arises */
|
|
/* when the UA or SA failed to send an authenticator for requests */
|
|
/* or registrations in a protected scope. */
|
|
|
|
#define SLP_AUTHENTICATION_FAILED -7
|
|
|
|
/* If the SLP framework supports authentication, this error arises */
|
|
/* when a authentication on an SLP message failed */
|
|
|
|
#define SLP_INVALID_UPDATE -13
|
|
|
|
/* An update for a non-existing registration was issued, or the */
|
|
/* update includes a service type or scope different than that in */
|
|
/* the initial registration, etc. */
|
|
|
|
#define SLP_REFRESH_REJECTED -15
|
|
|
|
/* The SA attempted to refresh a registration more frequently */
|
|
/* than the minimum refresh interval. The SA should call the */
|
|
/* appropriate API function to obtain the minimum refresh interval */
|
|
/* to use. */
|
|
|
|
#define SLP_NOT_IMPLEMENTED -17
|
|
|
|
/* If an unimplemented feature is used, this error is returned. */
|
|
|
|
#define SLP_BUFFER_OVERFLOW -18
|
|
|
|
/* An outgoing request overflowed the maximum network MTU size. */
|
|
/* The request should be reduced in size or broken into pieces and */
|
|
/* tried again. */
|
|
|
|
#define SLP_NETWORK_TIMED_OUT -19
|
|
|
|
/* When no reply can be obtained in the time specified by the */
|
|
/* configured timeout interval for a unicast request, this error */
|
|
/* is returned. */
|
|
|
|
#define SLP_NETWORK_INIT_FAILED -20
|
|
|
|
/* If the network cannot initialize properly, this error is */
|
|
/* returned. Will also be returned if an SA or DA agent (slpd) */
|
|
/* can not be contacted. See SLPRegReport() callback. */
|
|
|
|
#define SLP_MEMORY_ALLOC_FAILED -21
|
|
|
|
/* Out of memory error */
|
|
|
|
#define SLP_PARAMETER_BAD -22
|
|
|
|
/* If a parameter passed into an interface is bad, this error is */
|
|
/* returned. */
|
|
|
|
#define SLP_NETWORK_ERROR -23
|
|
|
|
/* The failure of networking during normal operations causes this */
|
|
/* error to be returned. */
|
|
|
|
#define SLP_INTERNAL_SYSTEM_ERROR -24
|
|
|
|
/* 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. */
|
|
|
|
#define SLP_HANDLE_IN_USE -25
|
|
|
|
/* In the C API, 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. */
|
|
|
|
#define SLP_TYPE_ERROR -26
|
|
|
|
|
|
#ifndef UNICAST_NOT_SUPPORTED
|
|
/* The SLP UA needs to send a unicast query to a SA because this SA has */
|
|
/* sent a packet > MTU size */
|
|
# define SLP_RETRY_UNICAST -27
|
|
#endif
|
|
|
|
|
|
/* If the API supports type checking of registrations against */
|
|
/* service type templates, this error can arise if the attributes */
|
|
/* in a registration do not match the service type template for */
|
|
/* the service. */
|
|
|
|
/*==========================================================================*/
|
|
/* SLPBoolean */
|
|
/*------------ */
|
|
/* The SLPBoolean enum is used as a boolean flag. */
|
|
typedef enum
|
|
{
|
|
SLP_FALSE = 0,
|
|
SLP_TRUE = 1
|
|
} SLPBoolean;
|
|
|
|
|
|
/*==========================================================================*/
|
|
/* SLPSrvURL */
|
|
/*----------- */
|
|
/* The SLPSrvURL structure is filled in by the SLPParseSrvURL() function */
|
|
/* with information parsed from a character buffer containing a service */
|
|
/* URL. The fields correspond to different parts of the URL. Note that */
|
|
/* the structure is in conformance with the standard Berkeley sockets */
|
|
/* struct servent, with the exception that the pointer to an array of */
|
|
/* characters for aliases (s_aliases field) is replaced by the pointer */
|
|
/* to host name (s_pcHost field). */
|
|
typedef struct srvurl
|
|
{
|
|
char *s_pcSrvType;
|
|
/* A pointer to a character string containing the service */
|
|
/* type name, including naming authority. The service type */
|
|
/* name includes the "service:" if the URL is of the service: */
|
|
/* scheme. */
|
|
|
|
char *s_pcHost;
|
|
/* A pointer to a character string containing the host */
|
|
/* identification information. */
|
|
|
|
int s_iPort;
|
|
/* The port number, or zero if none. The port is only available */
|
|
/* if the transport is IP. */
|
|
|
|
char *s_pcNetFamily;
|
|
/* A pointer to a character string containing the network address */
|
|
/* family identifier. Possible values are "ipx" for the IPX */
|
|
/* family, "at" for the Appletalk family, and "" (i.e. the empty */
|
|
/* string) for the IP address family. */
|
|
|
|
char *s_pcSrvPart;
|
|
/* The remainder of the URL, after the host identification. */
|
|
|
|
} SLPSrvURL;
|
|
/*=========================================================================*/
|
|
|
|
|
|
#if(!defined SLPHANDLE_INTERNAL)
|
|
|
|
/*=========================================================================*/
|
|
typedef void* SLPHandle;
|
|
/* */
|
|
/* The SLPHandle type is returned by SLPOpen() and is a parameter to all */
|
|
/* SLP functions. It serves as a handle for all resources allocated on */
|
|
/* behalf of the process by the SLP library. The type is opaque, since */
|
|
/* the exact nature differs depending on the implementation. */
|
|
/*=========================================================================*/
|
|
#endif
|
|
|
|
|
|
|
|
/*=========================================================================*/
|
|
typedef void SLPCALLBACK SLPRegReport(SLPHandle hSLP,
|
|
SLPError errCode,
|
|
void *pvCookie);
|
|
/* */
|
|
/* The SLPRegReport callback type is the type of the callback function */
|
|
/* to the SLPReg(), SLPDereg(), and SLPDelAttrs() functions. */
|
|
/* */
|
|
/* hSLP The SLPHandle used to initiate the operation. */
|
|
/* */
|
|
/* errCode An error code indicating if an error occurred during the */
|
|
/* operation. */
|
|
/* */
|
|
/* pvCookie Memory passed down from the client code that called the */
|
|
/* original API function, starting the operation. May be NULL. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
/*=========================================================================*/
|
|
typedef SLPBoolean SLPCALLBACK SLPSrvTypeCallback(SLPHandle hSLP,
|
|
const char* pcSrvTypes,
|
|
SLPError errCode,
|
|
void *pvCookie);
|
|
/* */
|
|
/* The SLPSrvTypeCallback type is the type of the callback function */
|
|
/* parameter to SLPFindSrvTypes() function. If the hSLP handle */
|
|
/* parameter was opened asynchronously, the results returned through the */
|
|
/* callback MAY be uncollated. If the hSLP handle parameter was opened */
|
|
/* synchronously, then the returned results must be collated and */
|
|
/* duplicates eliminated. */
|
|
/* */
|
|
/* hSLP The SLPHandle used to initiate the operation. */
|
|
/* */
|
|
/* pcSrvTypes A character buffer containing a comma separated, null */
|
|
/* terminated list of service types. */
|
|
/* */
|
|
/* errCode An error code indicating if an error occurred during the */
|
|
/* operation. The callback should check this error code befor*/
|
|
/* processing the parameters. If the error code is other than*/
|
|
/* SLP_OK, then the API library may choose to terminate the */
|
|
/* outstanding operation. */
|
|
/* */
|
|
/* pvCookie Memory passed down from the client code that called the */
|
|
/* original API function, starting the operation. May be NULL*/
|
|
/* */
|
|
/* Returns The client code should return SLP_TRUE if more data is */
|
|
/* desired, otherwise return SLP_FALSE */
|
|
/*=========================================================================*/
|
|
|
|
|
|
/*=========================================================================*/
|
|
typedef SLPBoolean SLPCALLBACK SLPSrvURLCallback(SLPHandle hSLP,
|
|
const char* pcSrvURL,
|
|
unsigned short sLifetime,
|
|
SLPError errCode,
|
|
void *pvCookie);
|
|
/* */
|
|
/* The SLPSrvURLCallback type is the type of the callback function */
|
|
/* parameter to SLPFindSrvs() function. If the hSLP handle parameter */
|
|
/* was opened asynchronously, the results returned through the callback */
|
|
/* MAY be uncollated. If the hSLP handle parameter was opened */
|
|
/* synchronously, then the returned results must be collated and */
|
|
/* duplicates eliminated. */
|
|
/* */
|
|
/* hSLP The SLPHandle used to initiate the operation. */
|
|
/* */
|
|
/* pcSrvURL A character buffer containing the returned service URL. */
|
|
/* May be NULL if errCode not SLP_OK. */
|
|
/* */
|
|
/* sLifetime An unsigned short giving the life time of the service */
|
|
/* advertisement, in seconds. The value must be an unsigned */
|
|
/* integer less than or equal to SLP_LIFETIME_MAXIMUM. */
|
|
/* */
|
|
/* errCode An error code indicating if an error occurred during the */
|
|
/* operation. The callback should check this error code */
|
|
/* before processing the parameters. If the error code is */
|
|
/* other than SLP_OK, then the API library may choose to */
|
|
/* terminate the outstanding operation. SLP_LAST_CALL is */
|
|
/* returned when no more services are available and the */
|
|
/* callback will not be called again.. */
|
|
/* */
|
|
/* pvCookie Memory passed down from the client code that called the */
|
|
/* original API function, starting the operation. */
|
|
/* May be NULL. */
|
|
/* */
|
|
/* Returns The client code should return SLP_TRUE if more data is */
|
|
/* desired, otherwise return SLP_FALSE */
|
|
/*=========================================================================*/
|
|
|
|
|
|
/*=========================================================================*/
|
|
typedef SLPBoolean SLPCALLBACK SLPAttrCallback(SLPHandle hSLP,
|
|
const char* pcAttrList,
|
|
SLPError errCode,
|
|
void *pvCookie);
|
|
/* */
|
|
/* The SLPAttrCallback type is the type of the callback function */
|
|
/* parameter to SLPFindAttrs() function. */
|
|
/* */
|
|
/* The behavior of the callback differs depending on whether the */
|
|
/* attribute request was by URL or by service type. If the */
|
|
/* SLPFindAttrs() operation was originally called with a URL, the */
|
|
/* callback is called once regardless of whether the handle was opened */
|
|
/* asynchronously or synchronously. The pcAttrList parameter contains */
|
|
/* the requested attributes as a comma separated list (or is empty if no */
|
|
/* attributes matched the original tag list). */
|
|
/* */
|
|
/* If the SLPFindAttrs() operation was originally called with a service */
|
|
/* type, the value of pcAttrList and calling behavior depend on whether */
|
|
/* the handle was opened asynchronously or synchronously. If the handle */
|
|
/* was opened asynchronously, the callback is called every time the API */
|
|
/* library has results from a remote agent. The pcAttrList parameter */
|
|
/* MAY be uncollated between calls. It contains a comma separated list */
|
|
/* with the results from the agent that immediately returned results. */
|
|
/* If the handle was opened synchronously, the results must be collated */
|
|
/* from all returning agents and the callback is called once, with the */
|
|
/* pcAttrList parameter set to the collated result. */
|
|
/* */
|
|
/* hSLP The SLPHandle used to initiate the operation. */
|
|
/* */
|
|
/* pcAttrList A character buffer containing a comma separated, null */
|
|
/* terminated list of attribute id/value assignments, in SLP */
|
|
/* wire format; i.e. "(attr-id=attr-value-list)". */
|
|
/* */
|
|
/* errCode An error code indicating if an error occurred during the */
|
|
/* operation. The callback should check this error code */
|
|
/* before processing the parameters. If the error code is */
|
|
/* other than SLP_OK, then the API library may choose to */
|
|
/* terminate the outstanding operation. */
|
|
/* */
|
|
/* pvCookie Memory passed down from the client code that called the */
|
|
/* original API function, starting the operation. */
|
|
/* May be NULL. */
|
|
/* */
|
|
/* Returns The client code should return SLP_TRUE if more data is */
|
|
/* desired,otherwise return SLP_FALSE */
|
|
/*=========================================================================*/
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAPI SLPOpen(const char *pcLang,
|
|
SLPBoolean isAsync,
|
|
SLPHandle *phSLP);
|
|
/* */
|
|
/* Returns a SLPHandle handle in the phSLP parameter for the language */
|
|
/* locale passed in as the pcLang 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. However, SLP properties */
|
|
/* are not encapsulated by the handle; they are global. 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). */
|
|
/* */
|
|
/* pcLang A pointer to an array of characters containing the RFC 1766 */
|
|
/* Language Tag RFC 1766 for the natural language locale of */
|
|
/* requests and registrations issued on the handle. Pass in NULL */
|
|
/* or the empty string, "" to use the default locale */
|
|
/* */
|
|
/* isAsync An SLPBoolean 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 SLPError code */
|
|
/*=========================================================================*/
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP void SLPAPI SLPClose(SLPHandle hSLP);
|
|
/* */
|
|
/* Frees all resources associated with the handle. If the handle was */
|
|
/* invalid, the function returns silently. Any outstanding synchronous */
|
|
/* or asynchronous operations are cancelled so their callback functions */
|
|
/* will not be called any further. */
|
|
/* */
|
|
/* SLPHandle A SLPHandle handle returned from a call to SLPOpen(). */
|
|
/*=========================================================================*/
|
|
|
|
|
|
#ifndef MI_NOT_SUPPORTED
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAssociateIFList( SLPHandle hSLP, const char* McastIFList);
|
|
/* */
|
|
/* Associates a list of interfaces McastIFList on which multicast needs to */
|
|
/* be done with a particular SLPHandle hSLP. McastIFList is a comma */
|
|
/* separated list of host interface IP addresses. */
|
|
/* */
|
|
/* hSLP The SLPHandle with which the interface list is to */
|
|
/* be associated with. */
|
|
/* */
|
|
/* McastIFList A comma separated list of host interface IP */
|
|
/* addresses on which multicast needs to be done. */
|
|
/* */
|
|
/* Returns SLPError code */
|
|
/*=========================================================================*/
|
|
#endif /* MI_NOT_SUPPORTED */
|
|
|
|
|
|
#ifndef UNICAST_NOT_SUPPORTED
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAssociateIP( SLPHandle hSLP, const char* unicast_ip);
|
|
/* */
|
|
/* Associates an IP address unicast_ip with a particular SLPHandle hSLP. */
|
|
/* unicast_ip is the IP address of the SA/DA from which service is */
|
|
/* requested. */
|
|
/* */
|
|
/* hSLP The SLPHandle with which the unicast_ip address is */
|
|
/* to be associated with. */
|
|
/* */
|
|
/* unicast_ip IP address of the SA/DA from which service is */
|
|
/* requested. */
|
|
/* */
|
|
/* Returns SLPError code */
|
|
/*=========================================================================*/
|
|
#endif
|
|
|
|
|
|
#define SLP_REG_FLAG_FRESH (1)
|
|
#define SLP_REG_FLAG_WATCH_PID (1 << 1)
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAPI SLPReg(SLPHandle hSLP,
|
|
const char *pcSrvURL,
|
|
const unsigned short usLifetime,
|
|
const char *pcSrvType,
|
|
const char *pcAttrs,
|
|
SLPBoolean fresh,
|
|
SLPRegReport callback,
|
|
void *pvCookie);
|
|
/* */
|
|
/* Registers the URL in pcSrvURL having the lifetime usLifetime with the */
|
|
/* attribute list in pcAttrs. The pcAttrs list is a comma separated */
|
|
/* list of attribute assignments in the wire format (including escaping */
|
|
/* of reserved characters). The usLifetime parameter must be nonzero */
|
|
/* and less than or equal to SLP_LIFETIME_MAXIMUM. If the fresh flag is */
|
|
/* SLP_TRUE, then the registration is new (the SLP protocol FRESH flag */
|
|
/* is set) and the registration replaces any existing registrations. */
|
|
/* The pcSrvType parameter is a service type name and can be included */
|
|
/* for service URLs that are not in the service: scheme. If the URL is */
|
|
/* in the service: scheme, the pcSrvType parameter is ignored. If the */
|
|
/* fresh flag is SLP_FALSE, then an existing registration is updated. */
|
|
/* Registrations and updates take place in the language locale of the */
|
|
/* hSLP handle. */
|
|
/* */
|
|
/* hSLP The language specific SLPHandle on which to register the */
|
|
/* advertisement. */
|
|
/* */
|
|
/* pcSrvURL The URL to register. May not be the empty string. May not */
|
|
/* be NULL. Must conform to SLP Service URL syntax. */
|
|
/* SLP_INVALID_REGISTRATION will be returned if it does not. */
|
|
/* */
|
|
/* usLifetime An unsigned short giving the life time of the service */
|
|
/* advertisement, in seconds. The value must be an unsigned */
|
|
/* integer less than or equal to SLP_LIFETIME_MAXIMUM and */
|
|
/* greater than zero. If SLP_LIFETIME_MAXIMUM is used, the */
|
|
/* registration will remain for the life of the calling */
|
|
/* process. Also, OpenSLP, will not allow registrations to */
|
|
/* be made with SLP_LIFETIME_MAXIMUM unless */
|
|
/* SLP_REG_FLAG_WATCH_PID is also used */
|
|
/* */
|
|
/* pcSrvType This parameter is ALWAYS ignored since the SLP Service URL */
|
|
/* syntax required for the pcSrvURL encapsulates the service */
|
|
/* type. */
|
|
/* */
|
|
/* pcAttrs A comma separated list of attribute assignment expressions */
|
|
/* for the attributes of the advertisement. Use empty string,*/
|
|
/* "" for no attributes. */
|
|
/* */
|
|
/* fresh Use of non-fresh registrations is deprecated. SLP_TRUE */
|
|
/* must be passed in for this parameter or SLP_BAD_PARAMETER */
|
|
/* will be returned */
|
|
/* */
|
|
/* callback A SLPRegReport callback to report the operation completion */
|
|
/* status. */
|
|
/* */
|
|
/* pvCookie Memory passed to the callback code from the client. May be*/
|
|
/* NULL. */
|
|
/* */
|
|
/* Returns: If an error occurs in starting the operation, one of the */
|
|
/* SLPError codes is returned. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAPI SLPDereg(SLPHandle hSLP,
|
|
const char *pcSrvURL,
|
|
SLPRegReport callback,
|
|
void *pvCookie);
|
|
/* */
|
|
/* Deregisters the advertisement for URL pcURL in all scopes where the */
|
|
/* service is registered and all language locales. The deregistration */
|
|
/* is not just confined to the locale of the SLPHandle, it is in all */
|
|
/* locales. The API library is required to perform the operation in all */
|
|
/* scopes obtained through configuration. */
|
|
/* */
|
|
/* hSLP The language specific SLPHandle to use for deregistering. */
|
|
/* */
|
|
/* pcSrvURL The SLP Service URL to deregister. May not be the empty */
|
|
/* string. May not be NULL. Must conform to SLP Service URL */
|
|
/* syntax or SLP_INVALID_REGISTRATION will be returned. */
|
|
/* */
|
|
/* callback A callback to report the operation completion status. */
|
|
/* */
|
|
/* pvCookie Memory passed to the callback code from the client. May be*/
|
|
/* NULL. */
|
|
/* */
|
|
/* Returns: If an error occurs in starting the operation, one of the */
|
|
/* SLPError codes is returned. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAPI SLPDelAttrs(SLPHandle hSLP,
|
|
const char *pcSrvURL,
|
|
const char *pcAttrs,
|
|
SLPRegReport callback,
|
|
void *pvCookie);
|
|
/* */
|
|
/* Delete the selected attributes in the locale of the SLPHandle. The */
|
|
/* API library is required to perform the operation in all scopes */
|
|
/* obtained through configuration. */
|
|
/* */
|
|
/* hSLP The language specific SLPHandle to use for deleting */
|
|
/* attributes. */
|
|
/* */
|
|
/* pcSrvURL The SLP Service URL of the advertisement from which the */
|
|
/* attributes should be deleted. May not be the empty string. */
|
|
/* */
|
|
/* pcAttrs A comma separated list of attribute ids for the attributes */
|
|
/* to deregister. May not be the empty string. */
|
|
/* */
|
|
/* callback A callback to report the operation completion status. */
|
|
/* */
|
|
/* pvCookie Memory passed to the callback code from the client. May be*/
|
|
/* NULL. */
|
|
/* */
|
|
/* Returns If an error occurs in starting the operation, one of the */
|
|
/* SLPError codes is returned. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAPI SLPFindSrvTypes(SLPHandle hSLP,
|
|
const char *pcNamingAuthority,
|
|
const char *pcScopeList,
|
|
SLPSrvTypeCallback callback,
|
|
void *pvCookie);
|
|
/* */
|
|
/* The SLPFindSrvType() function issues an SLP service type request for */
|
|
/* service types in the scopes indicated by the pcScopeList. The */
|
|
/* results are returned through the callback parameter. The service */
|
|
/* types are independent of language locale, but only for services */
|
|
/* registered in one of scopes and for the indicated naming authority. */
|
|
/* */
|
|
/* If the naming authority is "*", then results are returned for all */
|
|
/* naming authorities. If the naming authority is the empty string, */
|
|
/* i.e. "", then the default naming authority, "IANA", is used. "IANA" */
|
|
/* is not a valid naming authority name, and it is a PARAMETER_BAD error */
|
|
/* to include it explicitly. */
|
|
/* */
|
|
/* The service type names are returned with the naming authority intact. */
|
|
/* If the naming authority is the default (i.e. empty string) then it */
|
|
/* is omitted, as is the separating ".". Service type names from URLs */
|
|
/* of the service: scheme are returned with the "service:" prefix */
|
|
/* intact. See RFC 2609 for more information on the syntax of service */
|
|
/* type names. */
|
|
/* */
|
|
/* hSLP The SLPHandle on which to search for types. */
|
|
/* */
|
|
/* pcNamingAuthority The naming authority to search. Use "*" for all */
|
|
/* naming authorities and the empty string, "", for */
|
|
/* the default naming authority. */
|
|
/* */
|
|
/* pcScopeList A pointer to a string containing comma separated */
|
|
/* list of scope names to search for service types. */
|
|
/* May not be the empty string, "". */
|
|
/* */
|
|
/* callback A callback function through which the results of */
|
|
/* the operation are reported. */
|
|
/* */
|
|
/* pvCookie Memory passed to the callback code from the client.*/
|
|
/* May be NULL. */
|
|
/* */
|
|
/* Returns If an error occurs in starting the operation, one */
|
|
/* of the SLPError codes is returned. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAPI SLPFindSrvs(SLPHandle hSLP,
|
|
const char *pcServiceType,
|
|
const char *pcScopeList,
|
|
const char *pcSearchFilter,
|
|
SLPSrvURLCallback callback,
|
|
void *pvCookie);
|
|
/* */
|
|
/* Issue the query for services on the language specific SLPHandle and */
|
|
/* return the results through the callback. The parameters determine */
|
|
/* the results */
|
|
/* */
|
|
/* hSLP The language specific SLPHandle on which to search for */
|
|
/* services. */
|
|
/* */
|
|
/* pcServiceType The Service Type String, including authority string if */
|
|
/* any, for the request, such as can be discovered using */
|
|
/* SLPSrvTypes(). This could be, for example */
|
|
/* "service:printer:lpr" or "service:nfs". May not be */
|
|
/* the empty string or NULL. */
|
|
/* */
|
|
/* */
|
|
/* pcScopeList A pointer to a char containing comma separated list of */
|
|
/* scope names. Pass in the NULL or the empty string "" */
|
|
/* to find services in all the scopes the local host is */
|
|
/* configured query. */
|
|
/* */
|
|
/* pcSearchFilter A query formulated of attribute pattern matching */
|
|
/* expressions in the form of a LDAPv3 Search Filter. */
|
|
/* If this filter is NULL or empty, i.e. "", all */
|
|
/* services of the requested type in the specified scopes */
|
|
/* are returned. */
|
|
/* */
|
|
/* callback A callback function through which the results of the */
|
|
/* operation are reported. May not be NULL */
|
|
/* */
|
|
/* pvCookie Memory passed to the callback code from the client. */
|
|
/* May be NULL. */
|
|
/* */
|
|
/* Returns: If an error occurs in starting the operation, one of */
|
|
/* the SLPError codes is returned. */
|
|
/* */
|
|
/*=========================================================================*/
|
|
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAPI SLPFindAttrs(SLPHandle hSLP,
|
|
const char *pcURLOrServiceType,
|
|
const char *pcScopeList,
|
|
const char *pcAttrIds,
|
|
SLPAttrCallback callback,
|
|
void *pvCookie);
|
|
/* */
|
|
/* This function returns service attributes matching the attribute ids */
|
|
/* for the indicated service URL or service type. If pcURLOrServiceType */
|
|
/* is a service URL, the attribute information returned is for that */
|
|
/* particular advertisement in the language locale of the SLPHandle. */
|
|
/* */
|
|
/* If pcURLOrServiceType is a service type name (including naming */
|
|
/* authority if any), then the attributes for all advertisements of that */
|
|
/* service type are returned regardless of the language of registration. */
|
|
/* Results are returned through the callback. */
|
|
/* */
|
|
/* The result is filtered with an SLP attribute request filter string */
|
|
/* parameter, the syntax of which is described in RFC 2608. If the filter */
|
|
/* string is the empty string, i.e. "", all attributes are returned. */
|
|
/* */
|
|
/* hSLP The language specific SLPHandle on which to search */
|
|
/* for attributes. */
|
|
/* */
|
|
/* pcURLOrServiceType The service URL or service type. See RFC 2608 for */
|
|
/* URL and service type syntax. May not be the empty */
|
|
/* string. */
|
|
/* */
|
|
/* pcScopeList A pointer to a char containing a comma separated */
|
|
/* list of scope names. Pass in NULL or the empty */
|
|
/* string "" to find services in all the scopes the */
|
|
/* local host is configured query. */
|
|
/* */
|
|
/* pcAttrIds A comma separated list of attribute ids to return. */
|
|
/* Use NULL or the empty string, "", to indicate all */
|
|
/* values. Wildcards are not currently supported */
|
|
/* */
|
|
/* callback A callback function through which the results of */
|
|
/* the operation are reported. */
|
|
/* */
|
|
/* pvCookie Memory passed to the callback code from the client.*/
|
|
/* May be NULL. */
|
|
/* */
|
|
/* Returns: If an error occurs in starting the operation, one */
|
|
/* of the SLPError codes is returned. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP unsigned short SLPAPI SLPGetRefreshInterval();
|
|
/* */
|
|
/* Returns the maximum across all DAs of the min-refresh-interval */
|
|
/* attribute. This value satisfies the advertised refresh interval */
|
|
/* bounds for all DAs, and, if used by the SA, assures that no refresh */
|
|
/* registration will be rejected. If no DA advertises a min-refresh- */
|
|
/* interval attribute, a value of 0 is returned. */
|
|
/* */
|
|
/* Returns: If no error, the maximum refresh interval value allowed by all */
|
|
/* DAs (a positive integer). If no DA advertises a */
|
|
/* min-refresh-interval attribute, returns 0. If an error occurs,*/
|
|
/* returns an SLP error code. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAPI SLPFindScopes(SLPHandle hSLP,
|
|
char** ppcScopeList);
|
|
/* */
|
|
/* Sets ppcScopeList parameter to a pointer to a comma separated list */
|
|
/* including all available scope values. The list of scopes comes from */
|
|
/* a variety of sources: the configuration file's net.slp.useScopes */
|
|
/* property, unicast to DAs on the net.slp.DAAddresses property, DHCP, */
|
|
/* or through the DA discovery process. If there is any order to the */
|
|
/* scopes, preferred scopes are listed before less desirable scopes. */
|
|
/* There is always at least one name in the list, the default scope, */
|
|
/* "DEFAULT". */
|
|
/* */
|
|
/* hSLP The SLPHandle on which to search for scopes. */
|
|
/* */
|
|
/* ppcScopeList A pointer to char pointer into which the buffer pointer is */
|
|
/* placed upon return. The buffer is null terminated. The */
|
|
/* memory should be freed by calling SLPFree(). */
|
|
/* */
|
|
/* Returns: If no error occurs, returns SLP_OK, otherwise, the a */
|
|
/* ppropriate error code. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAPI SLPParseSrvURL(const char *pcSrvURL,
|
|
SLPSrvURL** ppSrvURL);
|
|
/* */
|
|
/* Parses the URL passed in as the argument into a service URL structure */
|
|
/* and returns it in the ppSrvURL pointer. If a parse error occurs, */
|
|
/* returns SLP_PARSE_ERROR. The structure returned in ppSrvURL should be */
|
|
/* freed with SLPFreeURL(). If the URL has no service part, the */
|
|
/* s_pcSrvPart string is the empty string, "", i.e. not NULL. If */
|
|
/* pcSrvURL is not a service: URL, then the s_pcSrvType field in the */
|
|
/* returned data structure is the URL's scheme, which might not be the */
|
|
/* same as the service type under which the URL was registered. If the */
|
|
/* transport is IP, the s_pcTransport field is the empty string. If the */
|
|
/* transport is not IP or there is no port number, the s_iPort field is */
|
|
/* zero. */
|
|
/* */
|
|
/* pcSrvURL A pointer to a character buffer containing the null terminated */
|
|
/* URL string to parse. */
|
|
/* */
|
|
/* ppSrvURL A pointer to a pointer for the SLPSrvURL structure to receive */
|
|
/* the parsed URL. The memory should be freed by a call to */
|
|
/* SLPFree() when no longer needed. */
|
|
/* */
|
|
/* Returns: If no error occurs, the return value is SLP_OK. Otherwise, the */
|
|
/* appropriate error code is returned. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAPI SLPEscape(const char* pcInbuf,
|
|
char** ppcOutBuf,
|
|
SLPBoolean isTag);
|
|
/* */
|
|
/* Process the input string in pcInbuf and escape any SLP reserved */
|
|
/* characters. If the isTag parameter is SLPTrue, then look for bad tag */
|
|
/* characters and signal an error if any are found by returning the */
|
|
/* SLP_PARSE_ERROR code. The results are put into a buffer allocated by */
|
|
/* the API library and returned in the ppcOutBuf parameter. This buffer */
|
|
/* should be deallocated using SLPFree() when the memory is no longer */
|
|
/* needed. */
|
|
/* */
|
|
/* pcInbuf Pointer to he input buffer to process for escape */
|
|
/* characters. */
|
|
/* */
|
|
/* ppcOutBuf Pointer to a pointer for the output buffer with the SLP */
|
|
/* reserved characters escaped. Must be freed using */
|
|
/* SLPFree()when the memory is no longer needed. */
|
|
/* */
|
|
/* isTag When true, the input buffer is checked for bad tag */
|
|
/* characters. */
|
|
/* */
|
|
/* Returns: Return SLP_PARSE_ERROR if any characters are bad tag */
|
|
/* characters and the isTag flag is true, otherwise SLP_OK, */
|
|
/* or the appropriate error code if another error occurs. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAPI SLPUnescape(const char* pcInbuf,
|
|
char** ppcOutBuf,
|
|
SLPBoolean isTag);
|
|
/* */
|
|
/* Process the input string in pcInbuf and unescape any SLP reserved */
|
|
/* characters. If the isTag parameter is SLPTrue, then look for bad tag */
|
|
/* characters and signal an error if any are found with the */
|
|
/* SLP_PARSE_ERROR code. No transformation is performed if the input */
|
|
/* string is an opaque. The results are put into a buffer allocated by */
|
|
/* the API library and returned in the ppcOutBuf parameter. This buffer */
|
|
/* should be deallocated using SLPFree() when the memory is no longer */
|
|
/* needed. */
|
|
/* */
|
|
/* pcInbuf Pointer to he input buffer to process for escape */
|
|
/* characters. */
|
|
/* */
|
|
/* ppcOutBuf Pointer to a pointer for the output buffer with the SLP */
|
|
/* reserved characters escaped. Must be freed using */
|
|
/* SLPFree() when the memory is no longer needed. */
|
|
/* */
|
|
/* isTag When true, the input buffer is checked for bad tag */
|
|
/* characters. */
|
|
/* */
|
|
/* Returns: Return SLP_PARSE_ERROR if any characters are bad tag */
|
|
/* characters and the isTag flag is true, otherwise SLP_OK, */
|
|
/* or the appropriate error code if another error occurs. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP void SLPAPI SLPFree(void* pvMem);
|
|
/* */
|
|
/* Frees memory returned from SLPParseSrvURL(), SLPFindScopes(), */
|
|
/* SLPEscape(), and SLPUnescape(). */
|
|
/* */
|
|
/* pvMem A pointer to the storage allocated by the SLPParseSrvURL(), */
|
|
/* SLPEscape(), SLPUnescape(), or SLPFindScopes() function. */
|
|
/* Ignored if NULL. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP const char* SLPAPI SLPGetProperty(const char* pcName);
|
|
/* */
|
|
/* Returns the value of the corresponding SLP property name. The returned */
|
|
/* string is owned by the library and MUST NOT be freed. */
|
|
/* */
|
|
/* pcName Null terminated string with the property name, from */
|
|
/* Section 2.1 of RFC 2614. */
|
|
/* */
|
|
/* Returns: If no error, returns a pointer to a character buffer containing*/
|
|
/* the property value. If the property was not set, returns the */
|
|
/* default value. If an error occurs, returns NULL. The returned */
|
|
/* string MUST NOT be freed. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP void SLPAPI SLPSetProperty(const char *pcName,
|
|
const char *pcValue);
|
|
/* */
|
|
/* Sets the value of the SLP property to the new value. The pcValue */
|
|
/* parameter should be the property value as a string. */
|
|
/* */
|
|
/* pcName Null terminated string with the property name, from Section */
|
|
/* 2.1. of RFC 2614. */
|
|
/* */
|
|
/* pcValue Null terminated string with the property value, in UTF-8 */
|
|
/* character encoding. */
|
|
/*=========================================================================*/
|
|
|
|
|
|
/*=========================================================================*/
|
|
SLPEXP SLPError SLPAPI SLPParseAttrs(const char* pcAttrList,
|
|
const char *pcAttrId,
|
|
char** ppcAttrVal);
|
|
/* */
|
|
/* Used to get individual attribute values from an attribute string that */
|
|
/* is passed to the SLPAttrCallback */
|
|
/* */
|
|
/* pcAttrList (IN) A character buffer containing a comma separated, null */
|
|
/* terminated list of attribute id/value assignments, in */
|
|
/* SLP wire format; i.e. "(attr-id=attr-value-list)" */
|
|
/* */
|
|
/* pcAttrId (IN) The string indicating which attribute value to return. */
|
|
/* MUST not be null. MUST not be the empty string (""). */
|
|
/* */
|
|
/* ppcAttrVal (OUT) A pointer to a pointer to the buffer to receive */
|
|
/* attribute value. The memory should be freed by a call */
|
|
/* to SLPFree() when no longer needed. */
|
|
/* */
|
|
/* Returns: Returns SLP_PARSE_ERROR if an attribute of the specified id */
|
|
/* was not found otherwise SLP_OK */
|
|
/*=========================================================================*/
|
|
|
|
#if(defined __cplusplus)
|
|
}
|
|
#endif
|
|
|
|
#endif /* (!defined SLP_H_INCLUDED) */
|