Service Location Working Group Erik Guttman
INTERNET DRAFT James Kempf
Sun Microsystems
Don Provan
30 November 1997 Novell, Inc.
An API for Service Location
draft-ietf-svrloc-api-02.txt
Status of This Memo
This document is a submission by the Service Location Working Group
of the Internet Engineering Task Force (IETF). Comments should be
submitted to the srvloc@corp.home.net mailing list.
Distribution of this memo is unlimited.
This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute
working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at
any time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as ``work in progress.''
To learn the current status of any Internet-Draft, please check
the ``1id-abstracts.txt'' listing contained in the Internet-Drafts
Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (North
Europe), ftp.nis.garr.it (South Europe), munnari.oz.au (Pacific Rim),
ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast).
Abstract
The Service Location Protocol (SLP) provides a new way for clients to
dynamically discovery network services. With SLP, it is simple to
offer highly available services that require no user configuration
or communication with network administrators prior to use. This
document describes standardized API's for SLP in C and Java. The
API's are modular and are designed to allow implementions to
offer just the feature set needed. In addition, a standardized
configuration file format and a format for proxy registrations is
defined. The configuration file format allows SLP agents to set
network and other parameters in a portable way. The proxy file
format allows legacy services to be registered with SLP directory
Guttman, Kempf, Provan Expires 31 May 1998 [Page i]
Internet Draft Service Location API 30 November 1997
agents in cases where modifying the legacy service program code is
difficult or impossible.
Guttman, Kempf, Provan Expires 31 May 1998 [Page ii]
Internet Draft Service Location API 30 November 1997
Contents
Status of This Memo i
Abstract i
1. Introduction 1
1.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. File Formats 5
2.1. Configuration File Format . . . . . . . . . . . . . . . . 5
2.1.1. DA configuration . . . . . . . . . . . . . . . . 6
2.1.2. UA and SA Static Configuration . . . . . . . . . 6
2.1.3. Tracing and Logging . . . . . . . . . . . . . . . 7
2.1.4. Proxy Registration . . . . . . . . . . . . . . . 7
2.1.5. Networking Configuration Parameters . . . . . . . 8
2.1.6. Default Header Information . . . . . . . . . . . 9
2.1.7. Security . . . . . . . . . . . . . . . . . . . . 9
2.2. Proxy Registration File . . . . . . . . . . . . . . . . . 10
2.3. Proccessing Proxy and Configuration Files . . . . . . . . 10
3. Binding Independent Implementation Considerations 10
3.1. Multithreading . . . . . . . . . . . . . . . . . . . . . 11
3.2. Type Checking for Service Types . . . . . . . . . . . . . 11
3.3. Refreshing Registrations . . . . . . . . . . . . . . . . 11
3.4. Configuration File Processing . . . . . . . . . . . . . . 11
3.5. Attribute Types . . . . . . . . . . . . . . . . . . . . . 12
3.6. Removal of Duplicates . . . . . . . . . . . . . . . . . . 12
3.7. SA Implementation . . . . . . . . . . . . . . . . . . . . 12
4. C Language Binding 13
4.1. Constant Types . . . . . . . . . . . . . . . . . . . . . 13
4.1.1. URL Lifetimes . . . . . . . . . . . . . . . . . . 13
4.1.2. Error Codes . . . . . . . . . . . . . . . . . . . 13
4.2. Struct Types . . . . . . . . . . . . . . . . . . . . . . 16
4.2.1. SLPSrvURL . . . . . . . . . . . . . . . . . . . . 16
4.2.2. SLPConn . . . . . . . . . . . . . . . . . . . . . 17
4.2.3. SLPConn . . . . . . . . . . . . . . . . . . . . . 17
4.3. Opening and Closing a Connection . . . . . . . . . . . . 17
4.3.1. SLPOpen . . . . . . . . . . . . . . . . . . . . . 17
4.3.2. SLPClose . . . . . . . . . . . . . . . . . . . . 18
4.4. Protocol API . . . . . . . . . . . . . . . . . . . . . . 18
4.4.1. SLPReg . . . . . . . . . . . . . . . . . . . . . 18
4.4.2. SLPDereg . . . . . . . . . . . . . . . . . . . . 19
Guttman, Kempf, Provan Expires 31 May 1998 [Page iii]
Internet Draft Service Location API 30 November 1997
4.4.3. SLPFindSrvTypes . . . . . . . . . . . . . . . . . 20
4.4.4. SLPFindSrvs . . . . . . . . . . . . . . . . . . . 22
4.4.5. SLPFindAttrs . . . . . . . . . . . . . . . . . . 23
4.5. Miscellaneous Functions . . . . . . . . . . . . . . . . . 25
4.6. SLPFindScopes . . . . . . . . . . . . . . . . . . . . . . 25
4.7. SLPFree . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.7.1. SLPOpaqueToRadix64 . . . . . . . . . . . . . . . 26
4.7.2. SLPRadix64ToOpaque . . . . . . . . . . . . . . . 27
4.7.3. SLPEscape . . . . . . . . . . . . . . . . . . . . 28
4.7.4. SLPUnescape . . . . . . . . . . . . . . . . . . . 29
4.7.5. SLPGetProperty . . . . . . . . . . . . . . . . . 30
4.7.6. SLPSetProperty . . . . . . . . . . . . . . . . . 30
4.8. Implementation Notes . . . . . . . . . . . . . . . . . . 31
4.8.1. Initialization . . . . . . . . . . . . . . . . . 31
4.8.2. Multithreading . . . . . . . . . . . . . . . . . 31
4.8.3. Syntax for String Parameters . . . . . . . . . . 31
4.8.4. Client Side Syntax Checking . . . . . . . . . . . 32
4.8.5. Character Set Encoding . . . . . . . . . . . . . 32
4.8.6. System Properties . . . . . . . . . . . . . . . . 32
4.8.7. Registration and the Fresh Flag . . . . . . . . . 32
4.8.8. Memory Management . . . . . . . . . . . . . . . . 33
4.9. Examples . . . . . . . . . . . . . . . . . . . . . . . . 33
5. Java Language Binding 35
5.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 35
5.2. Basic Data Structures . . . . . . . . . . . . . . . . . . 36
5.2.1. Class ServiceLocationAttribute . . . . . . . . . 36
5.2.2. Class ServiceURL . . . . . . . . . . . . . . . . 38
5.3. SLP Access Interfaces . . . . . . . . . . . . . . . . . . 44
5.3.1. Interface Advertiser . . . . . . . . . . . . . . 44
5.3.2. Interface Locator . . . . . . . . . . . . . . . . 49
5.3.3. Interface TemplateRegistry . . . . . . . . . . . 54
5.4. The Service Location Manager . . . . . . . . . . . . . . 57
5.4.1. Class ServiceLocationManager . . . . . . . . . . 57
5.5. Service Type Template Introspection . . . . . . . . . . . 59
5.5.1. Interface ServiceLocationAttributeVerifier . . . 59
5.5.2. Interface ServiceLocationAttributeDescriptor . . 62
5.6. Exceptions . . . . . . . . . . . . . . . . . . . . . . . 64
5.6.1. Class ServiceLocationException . . . . . . . . . 64
5.6.2. Class ServiceLocationAuthenticationException . . 65
5.6.3. Class ServiceLocationCharsetNotUnderstoodException 65
5.6.4. Class ServiceLocationLanguageNotSupportedException 65
5.6.5. Class ServiceLocationScopeNotSupportedException . 66
5.6.6. Class ServiceLocationParseException . . . . . . . 66
5.6.7. Class ServiceLocationInvalidRegistrationException 67
5.6.8. Class ServiceLocationInternalSystemException . . 67
5.6.9. Class ServiceLocationInternalNetException . . . . 67
5.6.10. Class ServiceLocationInitNetException . . . . . . 68
5.7. Implementation Notes . . . . . . . . . . . . . . . . . . 68
Guttman, Kempf, Provan Expires 31 May 1998 [Page iv]
Internet Draft Service Location API 30 November 1997
5.7.1. Client Side Syntax Checking . . . . . . . . . . . 68
5.7.2. Character Set Encoding . . . . . . . . . . . . . 68
5.7.3. Language Locale Handling . . . . . . . . . . . . 69
5.7.4. Setting SLP System Properties . . . . . . . . . . 69
5.7.5. Implementing register() and addAttributes() . . . 69
5.7.6. Exceptions . . . . . . . . . . . . . . . . . . . 70
5.7.7. Multithreading . . . . . . . . . . . . . . . . . 70
5.7.8. Return of Unscoped Services . . . . . . . . . . . 71
5.7.9. Modular Implementations . . . . . . . . . . . . . 71
5.8. Examples . . . . . . . . . . . . . . . . . . . . . . . . 72
6. Internationalization Considerations 75
6.1. service: URL . . . . . . . . . . . . . . . . . . . . . . 75
6.2. Character Set Identification and Use . . . . . . . . . . 75
7. Security Considerations 76
1. Introduction
The Service Location API is designed to be a standardized way to
programmatically access the Service Location Protocol (SLP). The
API's allow client and service programs to be be written or modified
in a very simple manner to provide dynamic service discovery and
selection. Bindings in the C and Java languages are defined in this
document. In addition, a standardized format for configuration files
and for proxy registration files is presented. These files allow
SLP agents to configure network parameters and to register legacy
services that have not been SLP enabled.
1.1. Goals
The overall goal of the API is to enable source portability of
applications that use the API between different implementations of
SLP. The result should facilitate the adoption of SLP, and conversion
of clients and service programs to SLP.
The goals of the standardized configuration file and proxy file
formats are the following:
Simple Syntax
The configuration and proxy file formats are designed to be
simple, and easily parsable, but nevertheless, readable by
humans.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 1]
Internet Draft Service Location API 30 November 1997
Complete Coverage
The individual properties specified in the configuration
file format are designed to give complete coverage of all
interesting SLP, basic network, and other parameters that might
be of interest to a system administrator.
Securely Support Security
SLP's security requirements are supported by the configuration
file, but security information that should remain strictly
private, such as private keys, is left out.
The individual goals of the C and Java bindings are somewhat
different. For the C binding, the goals are:
Minimal but Complete
The C binding is designed to provide a minimal but complete
implementation of SLP. While the C binding does provide
complete support for the base SLP protocol, support for
additional features, such as service type templates [11], has
not been specified.
Simple Memory Management
The C binding is designed to have simple, transparent memory
management. Dynamic memory requirements are kept limited to
facilitate small memory or ROMable implementations.
Simple Data Structures
The protocol makes extensive use of strings, and this is
reflected in the C binding. The data structures are easy to
keep track of and do not require extensive dynamic allocation.
In addition, the API should be implementable on 16 bit
microcontrollers.
Limited Code Size
The C binding is designed so that the size of the resulting
object code is minimized.
The goals of the Java binding are:
Modular Implementation
In addition to complete access to the protocol, the Java
binding is designed to provide access to additional features,
Guttman, Kempf, Provan Expires 31 May 1998 [Page 2]
Internet Draft Service Location API 30 November 1997
such as service type templates. The design is organized such
that subsets for small memory or ROMable implementations can
leave off those features that are not of interest.
Reflect SLP Entities as Objects
The Java binding reflects the important entities in SLP
(service: URL's, attributes, etc.) as objects. The result is
an object-oriented API rather than a string-based one, as is
appropriate for Java's language emphasis.
Flexible Data Types
The Java binding data types are designed for flexible access.
For example, Vector objects are used consistently across the
API instead of arrays of objects because adding and removing
elements is considerably simpler.
Modular Memory Requirments
The Java binding allows various subsets to be dynamically
linked, so the API implementation only requires as much memory
as the feature set used by the client or service program.
1.2. Terminology
Service Location Protocol (SLP)
The underlying protocol allowing dynamic and scalable service
discovery. This protocol is specified in the Service Location
Protocol [5].
SLP framework
When a 'Service Location framework' is mentioned, it refers to
both the SLP implementation and interface implementation; ie.
whatever provides the SLP functionality to user level programs.
Directory Agent (DA)
A service which automatically gathers service advertisements
from SAs in order to provide them to UAs.
User Agent (UA)
This is the Service Location process or library which allows
SLP requests to be made on behalf of a client process. UAs
Guttman, Kempf, Provan Expires 31 May 1998 [Page 3]
Internet Draft Service Location API 30 November 1997
direct requests to DAs when they exist automatically. In their
absense, UAs make requests directly from SAs.
Service Agent (SA)
This is the Service Location process or library which allows
service software to register and deregister itself with the SLP
framework. The SA SHOULD also respond to UA requests directly
in the absense of DAs.
Service Advertisement
A service: URL possibly combined with service attributes.
These are distributed by the SLP framework to Directory Agents.
Service Type Template
A document which describes the syntax of the service: URL
for a given service type, the protocol the client will use
to make use of the service and a definition of all service
attributes: the meaning, defaults, constraints of each value
the attributes can take on. See [11] for more information o
service type templates. Each service type is identified by a
string (usually the same name as the protocol used to deliver
the service).
The service: URL
A service of a particular type announces its availability
with a service: URL which includes its service access point
(domain name and possibly its port number) and optionally basic
configuration parameters. The syntax of the service: URL is
defined in the service type template.
Service Attributes
The attributes associated with a given service. The values
that can be assigned to service attributes are defined by the
service type template.
Scope
A string used to control the availability of service
advertisements. Scopes are assigned by site administrators to
group services for many purposes, but chiefly as a means of
scalability. DAs assigned a scope will store only services
advertised with the same scope value. UAs SHOULD use a scope
string in requests whenever possible.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 4]
Internet Draft Service Location API 30 November 1997
Naming Authority (NA)
This is a 'suffix' to the service type string. It completely
changes the meaning of the service type. NAs are used
for private definitions of well known Service Types and
experimental Service Type extensions. The default NA is
"IANA", which may be omitted. Service types with the IANA
naming authority are registered with the Internet Assigned
Numbers Authority (see [11] for more information on the
registration procedure).
2. File Formats
This section describes the configuration and proxy registration file
formats. Both files are defined in the ASCII character set [1].
The location and name of the configuration file is system-dependent,
but implementations of the API are encouraged to locate it together
with other configuration files and name it consistently.
2.1. Configuration File Format
The configuration file format consists of a newline delimited list
of zero or more property definitions. Each property definition
corresponds to a particular configurable SLP, network, or other
parameter in one or more of the three SLP agents. The file format
grammer in ABNF [3] syntax is:
config-file = line-list
line-list = line line line-list
line = property-line comment-line
comment-line = ( "#" ";" ) 1*allchar newline
property-line = property newline
property-def = property "=" value
property = prop | prop "." property
prop = 1*char
value = integer / boolean / vector / string
integer = 1*digit
digit = "0" / "1" / "2" / "3" / "4" / "5"
"6" / "7" / "8" / "9"
boolean = "true" / "false"
newline = CR / ( CR LF )
vector = "[" value-list "]"
value-list = value / value "," value-list
string = 1*char
char = digit | alpha | other
Guttman, Kempf, Provan Expires 31 May 1998 [Page 5]
Internet Draft Service Location API 30 November 1997
alpha = ;Any ASCII alpha character, A-Z, a-z
other = ;All printable ASCII characters
; other than alpha and digit, with
; the exception of tab, space and
; newline.
allchar = char | tab | space
The properties break down into seven general areas. Each of the
following subsections describes an area and its properties.
2.1.1. DA configuration
Important configuration parameters for DA's are included in this
section. These are:
net.slp.isDA
A boolean indicating if SLP is to act as a DA. If false, not
run as a DA. Default is false.
net.slp.DAScopes
A vector of strings giving scope names for the DA. If absent,
the DA is unscoped. Ignored if isDA is false. Default is
unscoped.
net.slp.DAHeartBeat
A 64 bit integer giving the number of milliseconds for the
DA heartbeat. Default is 3 hours (10800000 milliseconds).
Ignored if isDA is false.
net.slp.isDAStateful
A boolean indicating if the DA will start stateful. Ignored if
isDA is false. Default is false.
2.1.2. UA and SA Static Configuration
This property gives the DA addresses that statically configured UA's
and SA's should use.
net.slp.DAAddresses
A vector of IP addresses or DNS-resolvable names giving the
DA's to use for statically configured UA's and SA's, along
Guttman, Kempf, Provan Expires 31 May 1998 [Page 6]
Internet Draft Service Location API 30 November 1997
with their scopes. Ignored if isDA is true. Default is none.
Addresses obtained via DHCP take precedence over these.
Scoped DAs are listed with a comma delimited list inside
brackets following the DA address. For example:
da1.freeb.org,
da2.freeb.org[scope1,scope2],
da3.freeb.org[scope3]
Here da1 has no scope, da 2 has scope1 and scope2, da3 has only
scope3.
2.1.3. Tracing and Logging
This section allows tracing and logging information to be printed by
the various agents.
net.slp.traceDATraffic
A boolean controlling printing of messges about traffic with
DA's. Default is false.
net.slp.traceReg
A boolean controlling printing of messages upon registration
and deregistration, including the dumping of registration
records of all existing registrations. Default is false.
net.slp.traceDrop
A boolean controlling printing of a message when a registration
is dropped for any reason. Default is false.
2.1.4. Proxy Registration
This property indicates where the proxy registration document is
located.
net.slp.proxyURL
A string containing a URL pointing to a document containing
proxy registrations that should be done when the DA or SA
starts up. Default is none.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 7]
Internet Draft Service Location API 30 November 1997
2.1.5. Networking Configuration Parameters
The properties in this section allow various network configuration
parameters to be set.
net.slp.isBroadcastOnly
A boolean indicating if use broadcast should be used instead of
multicast. Default is false.
net.slp.multicastRadius
A positive integer less than or equal to 32, giving the
multicast radius. Default is 32.
net.slp.TCPTimeout
A 16 bit integer giving the timeout on all TCP connections, in
milliseconds. Default is 1500 (1.5 seconds).
net.slp.maxWait
A 32 bit integer giving the timeout in milliseconds on
all requests. Default is 90000 ms. Settings should be in
increments of 500 ms.
net.slp.multicastTimeouts
A vector of 16 bit integers used as timeouts, in milliseconds,
to implement the multicast convergence alorithm. Ignored if
isDA is true. Default is: [ 500, 1000, 1500 ].
net.slp.passiveDADetection
A boolean indicating that DA discovery should be passive.
Ignored if isDA is true. Default is true.
net.slp.DADiscoveryTimeout
A 16 bit integer indicating the timeout, in milliseconds, for
active DA discovery. Ignored if isDA or passiveDADetection is
true. Default is 2000 (2 seconds).
net.slp.MTU
A 16 bit integer giving the network packet MTU, in bytes.
Default is 1400.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 8]
Internet Draft Service Location API 30 November 1997
net.slp.multicastInterfaces
Vector of strings giving the names of network interfaces on
which a DA or SA should listen for multicast. Default is
empty, i.e. just listen on the main network interface.
2.1.6. Default Header Information
This section contains defaults for the various SLP header fields.
net.slp.isMonolingual
A boolean indicating whether the monolingual flag should be
set. Default is true.
net.slp.locale
A two character ISO-639 [10] language code for the language
locale. Default is "en". Setting this property causes the
property value to become the default locale for SLP messages.
net.slp.characterEncoding
A string giving the the official name of the IANA character set
encoding. Default is "US-ASCII".
net.slp.maximumResults
A 16 bit integer giving the maximum number of results to return
for a request. Positive integers and -1 are legal values. If
-1, indicates that all results should be returned.
2.1.7. Security
The properties in this section allow security parameters to be
configured.
net.slp.publicKey
A radix-64 [12] public key for DA's and UA's. If present,
indicates that URL and attribute authentication should be used.
net.slp.cryptoalgorithm
A string indicating the cryptoalgorthm to use for
authenticating URL's and attributes. The default is
"md5WithRSAEncryption". Ignored if publicKey is absent.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 9]
Internet Draft Service Location API 30 November 1997
2.2. Proxy Registration File
The proxy registration file contains a group of registrations which a
DA or SA server (if one exists) registers when it starts up. These
registrations are primarily for older service programs that do not
internally support SLP and cannot be converted. The syntax of the
proxy registration file, in ABNF format [3], is as follows:
proxy-file = proxy-reg-list
proxy-reg-list= proxy-reg proxy-reg proxy-reg-list
proxy-reg = url-props attr-list newline
url-props = service-url ,lifetime `,lang
service-url = ;The registration's service: URL. See
; [11] for syntax.
lifetime = ;Positive integer <= 65536
language = ;Two character ISO-639 language code,
; see [10].
attr-list = attr-id =attr-val-list newline
attr = ;Attribute id, see [11]
; for syntax.
attr-val-list = attr-val attr-val ,attr-val-list
attr-val = ;Attribute value, see [11]
; for syntax.
newline = CR / ( CR LF )
2.3. Proccessing Proxy and Configuration Files
Implementations are encouraged to make processing of configuration
and proxy files as transparent as possible to clients of the API. At
the latest, errors must be caught when the relevent configuration or
proxy registration file item is used. At the earliest, errors may
be caught when the relevent file is loaded into the executing agent.
Errors should be reported by logging to the appropriate platform
logging file, error output, or log device, and the default value
substituted.
Configuration file loading must be complete prior to the initiation
of the first networking connection. Proxy registration may occur at
any point before the DA accepts the first network request.
3. Binding Independent Implementation Considerations
This section discusses a number of implementation considerations
independent of language binding, with language specific notes where
applicable.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 10]
Internet Draft Service Location API 30 November 1997
3.1. Multithreading
Implementations of both the C and Java API's are required to make
API calls thread-safe. This means that access to data structures
shared between threads must be co-ordinated to avoid corruption or
invalid access. One way to achieve this goal is to allow only one
thread at a time in the implementing library. Performance in such
an implementation will suffer, however. Therefore, where possible,
implementations are encouraged to make access thread-hot, allowing
multiple threads within the SLP API library.
3.2. Type Checking for Service Types
Service type templates [11] allow SLP registrations to be type
checked for correctness. Implementations of the API are free to
make use of service type information for type checking, but are not
required to do so.
3.3. Refreshing Registrations
SLP advertisements carry an explicit lifetime with them. After the
lifetime expires, the DA flushes the registration from it's cache.
Implementations of the SA API are encouraged to provide an automatic
refreshing capability, so that service advertiser applications can
simply register their services for as long as they continue running.
The SA API is required to deregister any such advertisements as soon
as the calling application exits.
If the underlying platform does not support multithreading,
implementing automatic refreshing may be difficult.
3.4. Configuration File Processing
DA's, SA's and UA's processing the configuration file, and DA's
processing the proxy registration file are required to log any errors
using whatever underlying error mechanism is appropriate for the
platform. Examples include include writing error messages to the
standard output, writing to a system logging device, or displaying
the errors to a logging window. After the error is reported, the
offending parameter must be set to the default and program execution
continued. In no case should the agent break off processing, abort
the program, or throw an exception if a file format error occurs.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 11]
Internet Draft Service Location API 30 November 1997
3.5. Attribute Types
Because SLP is a string protocol, attribute values have no type
information on the wire. All UA implementations and those SA and
DA implementations that choose to support type checking should use
the type rules described in [11] in order to convert from the on the
wire string representation to an object typed appropriately in the
language of implementation.
3.6. Removal of Duplicates
The UA implementation should always collate results to remove
duplicates. This is especially important for the results of the SLP
find attributes request for a service type and the find service type
request when there are no DA's. The request will be multicast to all
SA's, and the results will no doubt include duplicate values.
3.7. SA Implementation
An SA implementation requires as a minimum that service
advertisements be registered with a DA. They SHOULD be able to
respond to UA queries directly in the absense of a DA.
If the latter feature is implemented, the SA will run on the same
host, and need some way to service UA requests on behalf of all the
host's services. This SA must listen for TCP requests. Since only
one process per host may be bound to a particular TCP port, the
SA process will have to be a shared resource and communicate with
the different service processes using some form of interprocess
communication, as an SA server.
There is a subtle bending of the semantics of Service Location if
a SA and DA are collocated on the same host. On some socket based
implementations of IP multicast, the following occurs: Two sockets
are bound to the same UDP port. One of the sockets has joined a
multicast group, the other hasn't. A multicast datagram arriving for
that multicast group, for the port in question, is delivered to BOTH
sockets. Suppose a DA is listening for unicast datagrams on the SLP
port, while the SA is listening for multicast packets on the same
port. A multicast datagram arrives for the SA, but is delivered to
the DA as well. In the worst case, BOTH respond. This will possibly
supply redundant information (if the SA services are registered
with the DA.) Worse, the DA may reply with information which it
'shouldn't.' None of this is very serious, because the worst that
can happen is the UA will receive more information than it would have
otherwise. The UA will only receive correct information in any case;
it MUST satisfy the UAs request or it won't be returned.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 12]
Internet Draft Service Location API 30 November 1997
4. C Language Binding
The C language binding presents a minimal overhead implemention that
maps directly into the protocol. There is one C language function
per protocol request, with the exception of the SLPDereg() and
SLPDelAttrs() functions, which map into different uses of the SLP
deregister request. Parameters are string values or arrays of simple
struct's, and memory management is kept simple by requiring the user
to supply memory where possible, and having an explicit SLPFree()
function where the appearance of differently sized data structures
from the network make user-supplied memory impossible.
The return value from each function is a long. If the function
returned successfully, then the value contains the number of returned
items, the size of the dynamically allocated buffer returned, etc.
If an error occured, the return value is a negative integer error
code. If the no values were returned, then the return value is zero.
Clients can differentiate between errors and successful returns by
checking whether the return value is negative or positive.
4.1. Constant Types
4.1.1. URL Lifetimes
4.1.1.1. Synopsis
typedef enum {
SLP_LIFETIME_NONE = 0,
SLP_LIFETIME_DEFAULT = 108000,
SLP_LIFETIME_PERMANENT = -1
} SLPURLLifetime;
4.1.1.2. Description
The SLPURLLifetime enum type contains URL lifetime values that are
frequently used. The SLP_LIFETIME_DEFAULT value corresponds to the
CONFIG_INTERVAL_1 in [5].
4.1.2. Error Codes
4.1.2.1. Synopsis
typedef enum {
Guttman, Kempf, Provan Expires 31 May 1998 [Page 13]
Internet Draft Service Location API 30 November 1997
SLP_OK = 0,
SLP_LANG_NOT_SUPPORTED = -1,
SLP_PROTOCOL_PARSE_ERR = -2,
SLP_INVALID_REGISTRATION = -3,
SLP_SCOPE_NOT_SUPPORTED = -4,
SLP_CHARSET_NOT_UNDERSTOOD = -5,
SLP_AUTHENTICATION_INVALID = -6,
SLP_AUTHENTICATION_FAILED = -7,
SLP_BUFFER_OVERFLOW = -9,
SLP_REQUEST_TIMED_OUT = -10,
SLP_COULD_NOT_INIT_NET_RESOURCES = -11,
SLP_COULD_NOT_ALLOCATE_MEMORY = -12,
SLP_PARAMETER_BAD = -13,
SLP_INTERNAL_NET_ERROR = -14,
SLP_INTERNAL_SYSTEM_ERROR = -15
} SLPError ;
4.1.2.2. Description
The SLPError enum contains error codes that are returned from API
functions.
The SLP protocol will only return an error code when an operation
fails completely. The following errors report SLP protocol problems.
The problem could be in the data supplied by the application or in
the interaction of the local SLP implementation with a remote agent.
In the latter case, the error can only be taken as a hint. Different
remote agents may have returned several different errors. SLP might
pick one to return to the operation, but it cannot guarantee that's
the primary cause of the failure.
SLP_LANG_NOT_SUPPORTED
No DA or SA has service advertisement 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.
SLP_PROTOCOL_PARSE_ERR
The SLP message was rejected by a remote SLP entity. The API
returns this error only when no information was retrieved,
and at least one SA or DA indicated a protocol error.
This suggests an implementation error in either the local
implementation or some other SLP implementation on the network.
It can also be caused by damage to the packet in the network.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 14]
Internet Draft Service Location API 30 November 1997
SLP_INVALID_REGISTRATION
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 will not return the error if at least one DA
accepted the registration.
SLP_SCOPE_NOT_SUPPORTED
The API may return this error code if the indicated scope is
not known. For example, if a DA is configured to allow only
particular scopes, a request using a scope not in that list
would result in this error.
SLP_CHARSET_NOT_UNDERSTOOD
The API returns this error code if it does not understand the
indicated character set, or if the operation fails because no
DA or SA understands the character set, and the request cannot
be converted into a more common character set such as ASCII.
SLP_AUTHENTICATION_INVALID
If the SLP framework supports authentication, this error will
arise when a remote DA fails to accept a registration. This
error will not occur if a UA rejects a reply to a request: The
UA will simply silently discard (and possibly log) the rejected
reply.
The following errors are generated through a program interacting with
the API and SLP implementation. The operation failed.
SLP_NOT_SUPPORTED_YET
If a particular feature is used that is not implemented in the
API, this error is returned.
SLP_REQUEST_TIMED_OUT
When no reply can be obtained in the time specified by the
configured timeout interval, this error is returned instead.
SLP_COULD_NOT_INIT_NET_RESOURCES
If the SLP framework cannot initialize properly, this error
will be returned.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 15]
Internet Draft Service Location API 30 November 1997
SLP_COULD_NOT_ALLOCATE_MEMORY
If the API fails to allocate memory, the operation is aborted
and returns this.
SLP_PARAMETER_BAD
If a parameter passed into an interface is bad, this error is
returned.
SLP_INTERNAL_NET_ERROR
The failure of networking during normal operations causes this
error to be 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.
4.2. Struct Types
4.2.1. SLPSrvURL
4.2.1.1. Synopsis
typedef struct srvurl {
char *s_pcURL;
long s_lifetime;
} SLPSrvURL;
4.2.1.2. Description
Arrays of SLPSrvURL structs are passed to the SLPReg() function to
register services and to the SLPFindSrvs() function to hold services
returned from a query. The values of s_lifetime are restricted to
1 to 65535 and indicate the number of seconds that the advertisment
should remain valid.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 16]
Internet Draft Service Location API 30 November 1997
4.2.2. SLPConn
4.2.2.1. Synopsis
typedef void* SLPConn;
The SLPConn type is returned by SLPOpen() and is a parameter to all
SLP functions. It serves as a handle for the SLP connection. The
type is opaque, since the exact nature differs depending on the
implementation.
4.2.3. SLPConn
4.2.3.1. Synopsis
typedef unsigned char* SLPOpaque;
The SLPOpaque type models the SLP OPAQUE attribute value type.
Opaques are converted to strings for transmission across the wire,
but can be used to model any other type.
4.3. Opening and Closing a Connection
4.3.1. SLPOpen
4.3.1.1. Synopsis
SLPConn SLPOpen(const char *pcLang);
4.3.1.2. Description
Returns a SLPConn handle for the language locale passed in as a
parameter. The handle encapsulates the language locale for SLP
requests issued through the handle, and any other resources required
by the implementation. If an error occurs, returns NULL.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 17]
Internet Draft Service Location API 30 November 1997
4.3.1.3. Parameters
pcLang
A pointer to an array of characters containing the two
character ISO-639 [10] code for the natural language locale of
requests issued on the handle. May not be NULL.
4.3.2. SLPClose
4.3.2.1. Synopsis
void SLPClose(SLPConn conn);
4.3.2.2. Description
Closes the SLP connection on the handle, and frees all resources
associated with the handle. If the handle was invalid, the function
returns silently. Ignored if NULL.
4.3.2.3. Parameters
SLPConn
A SLPConn connection handle returned from a call to SLPOpen().
4.4. Protocol API
4.4.1. SLPReg
4.4.1.1. Synopsis
long SLPReg(SLPConn conn,
SLPSrvURL *pURL,
const char *pcAttrs);
4.4.1.2. Description
Registers the service: URL in the pURL struct with the attribute
list in pcAttr. A call to SLPReg() with a URL that has already
Guttman, Kempf, Provan Expires 31 May 1998 [Page 18]
Internet Draft Service Location API 30 November 1997
been registered in the language locale of the handle adds the new
values to attributes previously registered, if the update contains
attributes having the same id. Boolean attributes are merged using
logical ``and'', as they cannot be multivalued. Attributes with new
id's are added to the attribute set for the advertisement in the
language locale of the registration.
An attribute with the id "scope" is handled differently. It
determines the scope or scopes of the registration. DA's can be
configured to only accept registrations from particular scopes. If
the scope attribute of the registration does not match the scope of
the available DA's, then a SLP_SCOPE_NOT_SUPPORTED error is returned.
If no scope attribute is given, the advertisement is registered
unscoped.
4.4.1.3. Parameters
conn
The language specific connection on which to register the
advertisement. May not be NULL.
pURL
The service: URL to register. May not be NULL.
pcAttrs
A comma separated list of attribute assignment expressions for
the attributes of the advertisement. See Section 9. in [5]
for a description of the list format. May not be NULL. Use
empty string, "" for no attributes.
4.4.1.4. Returns
If no error occurs and the registration is a new registration, the
return value is 1. If the registration is an update, the return
value is 0. Otherwise, if an error occurs, one of the SLPError codes
is returned.
4.4.2. SLPDereg
4.4.2.1. Synopsys
long SLPDereg(SLPConn conn,
Guttman, Kempf, Provan Expires 31 May 1998 [Page 19]
Internet Draft Service Location API 30 November 1997
SLPSrvURL *pURL,
const char *pcAttrs);
4.4.2.2. Description
If pcAttrs is NULL, deregisters the advertisment for service: URL
pURL in all language locales, not just the locale of the connection.
If pcAttrs is not NULL, then only delete the selected attributes in
the locale of the connection.
4.4.2.3. Parameters
conn
The language specific connection on which to delete attributes,
or to use for deregistering. May not be NULL.
pURL
The service: URL to deregister or delete attributes from. May
not be NULL.
pcAttrs
A comma separated list of attribute id's for the attributes to
deregister. See Section 9. in [5] for a description of the
list format. If NULL, then the advertisment is deregistered.
4.4.2.4. Returns
If no error occurs, the return value is 0. Otherwise, if an error
occurs, one of the SLPError codes is returned.
4.4.3. SLPFindSrvTypes
4.4.3.1. Synopsis
long SLPFindSrvTypes(SLPConn conn,
const char* pcNamingAuthority,
const char* pcScope,
char** ppcSrvTypes,
long lSize);
Guttman, Kempf, Provan Expires 31 May 1998 [Page 20]
Internet Draft Service Location API 30 November 1997
The SLPSrvType() function issues an SLP service type request and
returns the result as an array of pointers to char in ppcSrvTypes.
The lSize parameter indicates the size of the ppcSrvTypes array.
The service types are returned independent of language locale, but
only for the scope passed as pcScope 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.
If pcScope is NULL, then only those advertisements having no scope
attribute are searched. The service type names are returned with the
naming authority included, i.e. as:
service-type "." naming-authority
4.4.3.2. Parameters
conn
The connection on which to search for types. May not be NULL.
pcNamingAuthority
The naming authority to search. Use "*" for all naming
authorities and the empty string, "", for the default naming
authority. May not be NULL.
pcScope
A pointer to a char containing the name of the scope attribute
advertisements to search are required to have. May not be
NULL. Use empty string, "", to indicate that the advertisements
to search have no scope attribute.
ppcSrvTypes
A pointer to an array of char* in which the returned scope
strings are placed. The service type strings themselves should
be deallocated using SLPFree() when no longer needed. If the
number of strings is less than the lSize parameter, the array
element after the last string is NULL. May not be NULL.
lSize
The number of array items in the ppcSrvTypes array.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 21]
Internet Draft Service Location API 30 November 1997
4.4.3.3. Returns
If no error occurs, the return value is the number of returned
strings in ppcSrvTypes. Otherwise, if an error occurs, one of the
SLPError codes is returned. If the ppcSrvTypes array does not
contain enough storage for all the returned strings, the return value
is SLP_PARAMETER_BAD, but the array contents are usable.
4.4.4. SLPFindSrvs
4.4.4.1. Synopsis
long SLPFindSrvs(SLPConn conn,
const char* pcQuery,
SLPSrvURL* pSrvURL,
long lSize);
4.4.4.2. Description
Issue the query for services on the language specific connection
and return the results in paSrvURL. The exact format of pcQuery is
described in Section 5.0 of [5]. The pcQuery string includes three
parts:
Service Type
The service type can be discovered using SLPSrvTypes().
Scope
The scope can be discovered using SLPFindScopes(). Note that
even if a scope is given, the result will also return services
that are unscoped, due to a peculiarity in SLP scope semantics
(see [5]).
Query
The query is formulated of attribute pattern matching
expressions in either a prefix or comma-separated list format.
The exact syntax of the query is described in Sections 5.3,
5.4, and 5.5 of [5].
Guttman, Kempf, Provan Expires 31 May 1998 [Page 22]
Internet Draft Service Location API 30 November 1997
4.4.4.3. Parameters
conn
The language specific connection on which to search for
services. May not be NULL.
pcQuery
The query string to use. May not be NULL.
pSrvURL
A pointer to an array of SLPSrvURL structs in which the
returned service: URL's are placed. The SLPSrvURL s_pcURL
strings should be deallocated using SLPFree() when no longer
needed. If the number of array elements is less than the lSize
parameter, the s_pcURL field of the array element after the
last string is NULL. May not be NULL.
lSize
The number of array items in the pSrvURL array.
4.4.4.4. Returns
If no error occurs, the return value is the number of returned
array items in pSrvURL. Otherwise, if an error occurs, one of the
SLPError codes is returned. If the pSrvURL array does not contain
enough storage for all the returned strings, the return value is
SLP_PARAMETER_BAD, but the array contents are usable.
4.4.5. SLPFindAttrs
4.4.5.1. Synopsis
long SLPFindAttrs(SLPConn conn,
const char* pcURL,
const char* pcScope,
const char* pcAttrIds,
char* pcAttrs,
long lSize);
Guttman, Kempf, Provan Expires 31 May 1998 [Page 23]
Internet Draft Service Location API 30 November 1997
4.4.5.2. Description
Return service attributes matching the attribute id's for the
indicated full or partial URL. If pcURL is a complete service: URL,
the attribute information returned is for that particular service in
the language locale of the connection. If pcURL is a partial URL,
then all attributes for the service type are returned regardless of
the language of registration. The syntax for a partial URL string is
given in Section 12 of [5].
The result is filtered with an SLP attribute request filter string
parameter, the syntax of which is described in Section 12 of [5]. If
the filter string is the empty string, i.e. "", all attributes are
returned.
4.4.5.3. Parameters
conn
The language specific connection on which to search for
attributes. May not be NULL.
pcURL
The full or partial URL. See Section 12 of [5] for partial URL
syntax. May not be NULL.
pcScope
The scope name. Use empty string, "", to indicate an unscoped
request. May not be NULL.
pcAttrIds
The filter string indicating which attribute values to return.
Use empty string, "", to indicate all values. Wildcards
matching all attribute id's having a particular prefix or
suffix are also possible. See Section 12 of [5] for the exact
format of the filter string. May not be NULL.
pcAttrs
A pointer to a buffer of char where the character string
containing a comma separated list of attribute assignment
expressions for the return is put. May not be NULL.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 24]
Internet Draft Service Location API 30 November 1997
lSize
The number of array items in the pcAttrs array.
4.4.5.4. Returns
If no error occurs, the return value is the number of characters in
pcAttrs. Otherwise, if an error occurs, one of the SLPError codes is
returned. If the pcAttrs array does not contain enough storage for
all the returned attributes, the return value is SLP_PARAMETER_BAD.
4.5. Miscellaneous Functions
4.6. SLPFindScopes
4.6.0.5. Synopsis
void SLPFindScopes(SLPConn conn,
char** ppcScopes,
long lSize);
4.6.0.6. Description
Returns an array of strings with all available scope values. The
list of scopes could be configured manually, determined with DHCP, or
built from the DA discovery process. If there is any order to the
scopes, preferred scopes are listed before less desirable scopes.
There will always be at least one string in the array, the empty
string, "", indicating unscoped.
4.6.0.7. Parameters
conn
The connection on which to search for scopes. May not be NULL.
ppcScopes
An array of pointers to char supplied by the caller to hold
the results. If the number of strings is less than the lSize
parameter, the array element after the last string is NULL. The
strings should be freed using SLPFree() when no longer needed.
May not be NULL.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 25]
Internet Draft Service Location API 30 November 1997
lSize
The number of array items in the ppcScopes array.
4.6.0.8. Returns
If no error occurs, the return value is the number of characters in
strings in the ppcScopes array. Otherwise, if an error occurs, one
of the SLPError codes is returned. If the ppcScopes array does not
contain enough storage for all the returned attributes, the return
value is SLP_PARAMETER_BAD, but the array contents are usable.
4.7. SLPFree
4.7.0.9. Synopsis
void SLPFree(char* pcStorage);
4.7.0.10. Description
Frees the storage pcStorage allocated by the SLP API. The
only storage that needs freeing are the char* returned from
SLPFindSrvTypes() and SLPFindScopes(), and the s_pcURL field
char* returned as part of the SLPSrvURL structs returned from
SLPFindSrvs().
4.7.0.11. Parameters
pcStorage
A pointer to the storage allocated through the SLP API. Ignored
if NULL.
4.7.1. SLPOpaqueToRadix64
4.7.1.1. Synopsis
logn SLPOpaqueToRadix64(const SLPOpaque opaque,
const long lOSize,
char* pcBuf,
long lSize);
Guttman, Kempf, Provan Expires 31 May 1998 [Page 26]
Internet Draft Service Location API 30 November 1997
4.7.1.2. Description
Convert an SLPOpaque into a radix-64 encoded string for transmission
over the wire. See [12] for a description of radix-64 format and [5]
for how it is used in SLP.
4.7.1.3. Parameters
opaque
The opaque value to convert. May not be NULL.
lOSize
The number of bytes in the opaque.
pcBuf
A client supplied buffer into which the null terminated
radix-64 value is put. May not be NULL.
lSize
The number of array elements in the pcBuf array.
4.7.1.4. Returns
Returns the number of characters in pcBuf or SLP_PARAMETER_BAD error
if the buffer overflows.
4.7.2. SLPRadix64ToOpaque
4.7.2.1. Synopsis
logn SLPRadix64ToOpaque(const char* pcRadix64,
SLPOpaque opaque,
long lSize);
Guttman, Kempf, Provan Expires 31 May 1998 [Page 27]
Internet Draft Service Location API 30 November 1997
4.7.2.2. Description
Convert a radix-64 encoded SLPOpaque into binary format. See [12]
for a description of radix-64 format and [5] for how it is used in
SLP.
4.7.2.3. Parameters
pcRadix64
The radix-64 value to convert, as a null terminated string.
May not be NULL.
opaque
A buffer containing storage for where the binary opaque should
be placed. May not be NULL.
lOSize
The number of bytes in the opaque.
4.7.3. SLPEscape
4.7.3.1. Synopsis
long SLPEscape(const char* pcEscapee
char* pcBuf,
long lSize);
4.7.3.2. Description
Escape any escapable characters in pcEscapee into the escape
format described in [5]. Use the currently active character
encoding established for the API via the property setting for
net.slp.characterEncoding.
4.7.3.3. Parameters
pcEscapee
Null terminated string to escape. May not be NULL.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 28]
Internet Draft Service Location API 30 November 1997
pcBuf
A buffer containing storage for where the escaped string is to
be placed. May not be NULL.
lSize
The number of bytes in pcBuf.
4.7.3.4. Returns
If no error, returns the number of bytes in pcBuf. If an error
ocurs, returns SLP_PARAMETER_BAD error if the buffer overflows.
4.7.4. SLPUnescape
4.7.4.1. Synopsis
long SLPUnescape(const char* pcUnescapee
char* pcBuf,
long lSize);
4.7.4.2. Description
Unescape any escapable characters in pcUnescapee out of the escape
format described in [5]. Use the currently active character
encoding established for the API via the property setting for
net.slp.characterEncoding.
4.7.4.3. Parameters
pcUnescapee
Null terminated string to escape. May not be NULL.
pcBuf
A buffer containing storage for where the unescaped string is
to be placed. May not be NULL.
lSize
The number of bytes in pcBuf.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 29]
Internet Draft Service Location API 30 November 1997
4.7.4.4. Returns
If no error, returns the number of bytes in pcBuf. If an error
ocurs, returns SLP_PARAMETER_BAD error if the buffer overflows.
4.7.5. SLPGetProperty
4.7.5.1. Synopsis
const char* SLPGetProperty(const char* pcName);
4.7.5.2. Description
Returns the value of the corresponding SLP property name, or NULL if
none.
4.7.5.3. Parameters
pcName
Null terminated string with the property name, from
Section 2.1. May not be NULL.
4.7.5.4. Returns
If no error, returns a pointer to the property value. If an error
occurs, returns NULL. The returned string should NOT be freed.
4.7.6. SLPSetProperty
4.7.6.1. Synopsis
void SLPSetProperty(const char* pcName,
const char* pcValue);
4.7.6.2. Description
Sets the value of the SLP property to the new value. The pcValue
parameter should be the property value as a string.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 30]
Internet Draft Service Location API 30 November 1997
4.7.6.3. Parameters
pcName
Null terminated string with the property name, from
Section 2.1. May not be NULL.
pcValue
Null terminated string with the property value, in character
format. May not be NULL.
4.8. Implementation Notes
4.8.1. Initialization
Dynamic link libraries are encouraged to initialize the SLP library
when linking occurs, provided the platform supports dynamically
linked library initialization. Statically linked applications are
required to initialize on the first call to SLPOpen().
4.8.2. Multithreading
Since C has no language level thread access package, access
to multithreading is necessarily platform specific. However,
implementations are required to be thread safe. At the grossest
level, thread safety can be achieved by simply locking the library
whenever a thread enters, but the lack of multithreaded access to the
library reduces performance.
At the next level, access to the library through the SLPConn handles
can be locked, so only one thread can invoke library operations on a
SLPConn handle at a time. The SLPConn handles may internally need
to store thread state in order to achieve this. Finally, at the
finest level, individual functions and data structures internal to
the SLP API implementation can be locked, so that the maximum amount
of throughput is obtained.
4.8.3. Syntax for String Parameters
Query strings, attribute registration lists, attribute deregistration
lists, and attribute selection lists follow the syntax described
in [5] for the appropriate requests. The API directly reflects the
strings passed in from clients into protocol requests, and directly
reflects out strings returned from protocol replies to clients. As a
consequence, clients are responsible for formatting request strings,
Guttman, Kempf, Provan Expires 31 May 1998 [Page 31]
Internet Draft Service Location API 30 November 1997
including escaping and converting opaque values to radix-64 encoded
strings. Similarly, on output, clients are required to unescape
strings and convert radix-64 encoded opaques to binary. Utility
functions are included to help in the process.
4.8.4. Client Side Syntax Checking
Implementations may do syntax checking of scope names, naming
authority names, and service type names on the client side, but
are not required to do so. Since the C API is designed to be a
thin layer over the protocol, some low memory SA implementations
may find extensive syntax checking on the client side to be
burdensome. If syntax checking uncovers an error in a parameter, the
SLP_PARAMETER_BAD error should be returned. If any parameter is NULL
and is required to be nonNULL, SLP_PARAMETER_BAD is returned.
4.8.5. Character Set Encoding
Implementations are required to support US-ASCII, LATIN1, and UTF8
IANA character set encodings, and are encouraged to support Unicode.
The net.slp.characterEncoding property supplies the currently active
encoding to use. The API must translate between the string property
value and the IANA MIB enum value to use in the protocol header.
4.8.6. System Properties
The system properties established in the configuration file are
accessable through the SLPGetProperties() and SLPSetProperties()
functions. Errors are checked when the property is used and, as
with parsing the configuration file, are logged. Program execution
continues without interruption by substituting the default for the
erroneous parameter. In general, individual agents should rarely be
required to override these properties, since they reflect properties
of the SLP network which are not of concern to individual agents.
If changes are required, system administrators should modify the
configuration file.
4.8.7. Registration and the Fresh Flag
Implementations are required to return the value of the SLP protocol
fresh flag received as part of the SLP reply to a registration
request, as the return value of SLPReg(). The client can use the
fresh flag to determine if the registration is new or if it is an
update.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 32]
Internet Draft Service Location API 30 November 1997
4.8.8. Memory Management
Character strings returned via the SLPFindSrvTypes(), SLPFindSrvs(),
and SLPFindScopes() functions should be freed when no longer needed
via the SLPFree() function. Character strings returned via the
SLPGetProperty() function should NOT be freed. Most functions
require the client to pass in an array of the appropriate data type
and an array size, and return the number of items in the array, or an
error if a buffer overflow occured.
4.9. Examples
Suppose web servers register themselves with the SLP framework. The
attributes they register are a scope, and index of all the home pages
available on the server. The homepages are listed as
<relative URL> "::" <title> "::" <description>
The web server code does the following:
long err = SLP_OK;
SLPConn sh = SLPOpen("en") /*an English connection*/
if( sh == NULL ) {
/*Deal with error.*/
}
/*Create the service: URL and attribute parameters.*/
SLPSrvURL surl =
{ "service:http://myhost.sun.com", /*the URL */
SLP_LIFETIME_DEFAULT }; /*default lifetime*/
const char* attrs =
"(SCOPE=ENGINEERING),"
"(HOME PAGES="
"schedule/index.html::Schedule::"
"This site contains updated timelines for all the work in"
"the F.L.O.R.B. project,"
"snort/releases.html::Bob Snort's Home::"
"Release engineer Bob posts results of all the builds "
"here,"
"specs/index.html::Specs galore::"
"Technical specifications for the F.L.O.R.B. and X872"
Guttman, Kempf, Provan Expires 31 May 1998 [Page 33]
Internet Draft Service Location API 30 November 1997
"projects.)";
err = SLPRegister(sh,surl,attrs);
if (err < 0 ) {
/*Deal with error.*/
}
A web browser uses the SLP framework to find a particular web site.
Unlike web indexing search engines, SLP keeps the information up to
date and the information is available within a few seconds after a
web server registers itself.
/*
* The client calls SL_Open, exactly as above.
*/
const char* srvtype = "http"; /*the service type */
const char* scope = "ENGINEERING"; /*the scope */
const char* attrids = "HOME PAGES"; /*the attribute id */
char* attrbuf[MAXBUF]; /*the return buffer*/
long err =
SLPFindAttrs(sh,srvtype,scope,attrids,attrbuf,MAXBUF);
if (err < 0 ) {
/*Deal with error.*/
}
/*
* The client will examine the AttrResult and
* choose a HOME PAGE
*/
const char* query =
"http/" /*the service type*/
"engineering/" /*the scope */
"Technical specifications " /*the description */
"for the F.L.O.R.B. and X872 "
"projects./";
SLPSrvURL surls[MAXURL];
Guttman, Kempf, Provan Expires 31 May 1998 [Page 34]
Internet Draft Service Location API 30 November 1997
err = SLPFindSrvs(sh,query,surls,MAXURL);
if( err < 0 ) {
/*Deal with error.*/
}
This will return a SLPService with the URL:
"service:http://myhost.sun.com"
The application can append on the "specs/index.html" from the
attribute to obtain a URL for the browser to use:
"http://myhost.sun.com/specs/index.html"
5. Java Language Binding
5.1. Introduction
The Java API is designed to model the various SLP entities in
classes and objects. API's are provided for SA, UA, and service
type template access capabilities. The ServiceLocationManager class
contains methods which return instances of objects implementing SA,
UA, and service type template access capability. Each of these
is modelled in an interface. The Locator interface provides UA
capability, the Advertiser interface provides SA capability, and the
TemplateRegistry provides access to service type templates. The
TemplateRegistry interface contains methods that return objects for
template introspection and attribute type checking. The ServiceURL
class and ServiceLocationAttribute class model the basic service:
URL and attribute concepts.
All SLP classes and interfaces are located within a single package.
The package name should begin with the name of the implementation and
conclude with the suffixnet.slp. Thus, the name for a hypothetical
implementation from the University of Michigan would look like:
edu.umich.net.slp
This follows the Java convention of prepending the top level DNS
domain name for the organization implementing the package onto the
organization's name and using that as the package prefix.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 35]
Internet Draft Service Location API 30 November 1997
5.2. Basic Data Structures
5.2.1. Class ServiceLocationAttribute
5.2.1.1. Synopsis
public final class ServiceLocationAttribute
extends Object
5.2.1.2. Description
The ServiceLocationAttribute class models SLP attributes. Instances
of this class are returned by Locator.findAttributes() and are
communicated along with register/deregister requests.
5.2.1.3. Constructors
public ServiceLocationAttribute(String id,Vector values)
Construct a service location attribute.
Parameters:
id
The attribute name. The String can consist of any Unicode
character.
values
A Vector of one or more attribute values. Vector contents
must be uniform in type and one of Integer, String, Boolean,
or byte[]. If the attribute is a keyword attribute, then
parameter should be null. String values can consist of any
Unicode character.
Throws:
IllegalArgumentException
Thrown if either parameter is null or the Vector contents has a
type mismatch.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 36]
Internet Draft Service Location API 30 November 1997
5.2.1.4. Instance Methods
public final Vector getValues()
Returns a cloned vector of attribute values, or null if the attribute
is a keyword attribute. If the attribute is single-valued, then the
vector contains only one object.
public final String getId()
Returns the attribute's name.
public final String getEscapedId()
Returns an escaped version of the id, suitable for inclusion in a
query. The character encoding used to convert escapable characters
to escape form is the encoding specified in the SLP configuration
file, or, if unset, the default Java encoding.
public final Vector getEscapedValues()
Returns a Vectors containing the escaped values as Strings,
suitable for inclusion in a query. Binary arrays are converted into
radix-64 [12] format and the character encoding used to convert
escapable characters to escape form is the encoding specified in the
SLP configuration file, or, if unset, the default Java encoding.
public boolean equals(Object o)
Overrides Object.equals().
public String toString()
Overrides Object.toString().
Guttman, Kempf, Provan Expires 31 May 1998 [Page 37]
Internet Draft Service Location API 30 November 1997
5.2.2. Class ServiceURL
5.2.2.1. Synopsis
public class ServiceURL extends Object
5.2.2.2. Description
The ServiceURL object models the SLP service: URL. These objects are
returned from service lookup requests, and describe the registered
services. The constructors provide access to various levels of the
service: URL BNF grammer.
5.2.2.3. Class Variables
public static final int NO\_PORT
Indicates that no port information is required or was returned for
this service: URL.
public static final int LIFETIME\_NONE
Indicates that the service: URL has no lifetime.
public static final int LIFETIME\_DEFAULT
The default service: URL lifetime.
public static final int LIFETIME\_PERMANENT
The service should last as long as the registering application
continues in execution.
5.2.2.4. Constructors
Guttman, Kempf, Provan Expires 31 May 1998 [Page 38]
Internet Draft Service Location API 30 November 1997
public ServiceURL(String serviceURL)
Construct a service: URL object.
Parameters:
serviceURL
The service: URL as a string.
Throws:
IllegalArgumentException
Thrown if parse errors occur in the parameter.
public ServiceURL(String sURL,int iLifetime)
Construct a service: URL object.
Parameters:
serviceURL
The service: URL as a string.
lifetime
The service advertisement lifetime.
Throws:
IllegalArgumentException
Thrown if parse errors occur in the parameter.
public ServiceURL(String serviceTypeAndNamingAuthority,
String servicePart,
int iLifetime)
Construct a service: URL object.
Parameters:
Guttman, Kempf, Provan Expires 31 May 1998 [Page 39]
Internet Draft Service Location API 30 November 1997
serviceTypeAndNamingAuthority
The name for a registered service type, including naming
authority. They are separated with a "."
servicePart
The host name or number, port, and URL path to the service.
lifetime
The duration of the registration in seconds.
Throws:
IllegalArgumentException
Thrown if parse errors occur in the parameter.
public ServiceURL(String serviceTypeAndNamingAuthority,
String login,
String sURLPath,
int iLifetime)
Construct a service: URL object.
Parameters:
serviceTypeAndNamingAuthority
The name for a registered service type, including naming
authority.
login
The host name or number, and port.
URLPath
The URL path to the service, if any.
lifetime
The service advertisement lifetime.
Throws:
Guttman, Kempf, Provan Expires 31 May 1998 [Page 40]
Internet Draft Service Location API 30 November 1997
IllegalArgumentException
Thrown if parse errors occur in any parameter.
public ServiceURL(String serviceType,
String namingAuthority,
String hostPort,
String sURLPath,
int iLifetime)
Construct a service: URL object.
Parameters:
serviceType
The name for a registered service type.
namingAuthority
The naming authority for the service.
hostPort
The machine name or IP address and TCP port number, if any.
URLPath
The URL path to the service, if any.
lifetime
The service advertisement lifetime.
Throws:
IllegalArgumentException
Thrown if parse errors occur in any parameter.
public ServiceURL(String serviceType,
String namingAuthority,
String address,
int iPort,
String URLPath,
int iLifetime)
Guttman, Kempf, Provan Expires 31 May 1998 [Page 41]
Internet Draft Service Location API 30 November 1997
Construct a service: URL object.
Parameters:
serviceType
The name for a service type.
namingAuthority
The naming authority for the service.
host
The machine name or IP address.
port
The TCP port number, if any. Use NO_PORT if none.
URLPath
The URL path to the service, if any.
lifetime
The service advertisement lifetime.
Throws:
IllegalArgumentException
Thrown if parse errors occur in any parameter.
5.2.2.5. Methods
public final String getServiceType()
Returns the service type name.
public final String getServicePart()
Guttman, Kempf, Provan Expires 31 May 1998 [Page 42]
Internet Draft Service Location API 30 November 1997
Returns the service part (host + port + URL path).
public final String getHost()
Returns the machine name or IP address.
public final int getPort()
Returns the port number, if any.
public final String getURLPath()
Returns the URL path description, if any.
public final int getLifetime()
Returns the service advertisement lifetime.
public final String getNamingAuthority()
Returns the naming authority for the ServiceURL. An empty string
means the default.
public final String
getServiceTypeAndNamingAuthority()
Returns the service type and naming authority.
public final String toString()
Returns formatted string with the service: URL.
Overrides Object.toString()
Guttman, Kempf, Provan Expires 31 May 1998 [Page 43]
Internet Draft Service Location API 30 November 1997
5.3. SLP Access Interfaces
5.3.1. Interface Advertiser
5.3.1.1. Synopsis
public interface Advertiser
5.3.1.2. Description
The Advertiser is the SA interface, allowing clients to register new
service instances with SLP, to change the attributes of existing
services, and to deregister service instances. New registrations
and modifications of attributes are made in the language locale
with which the Advertiser was created, deregistrations of service
instances are made for all locales.
5.3.1.3. Instance Methods
public abstract Locale getLocale()
Return the language locale with which this object was created.
public abstract Vector findScopes()
Returns a vector Strings giving known scope names. The vector
will always have at least one element: "", the empty string, for
unscoped.
public abstract void register(ServiceURL URL,
Vector scopeNames,
Vector attributes)
throws ServiceLocationException
Register a new service with SLP.
Parameters:
Guttman, Kempf, Provan Expires 31 May 1998 [Page 44]
Internet Draft Service Location API 30 November 1997
URL
The service: URL for the service.
vScopes
The SLP scopes of the service.
attributes
A vector of ServiceLocationAttribute objects describing the
service.
Throws :
IllegalArgumentException
Thrown if any parameter is null.
ServiceLocationCharsetNotSupportedException
Thrown if the SA server (if one exists) or DA does not support
the character set encoding set by the net.slp.characterEncoding
property.
ServiceLocationAuthenticationException
Thrown if one or more of the scopes are protected and the SLP
framework for the Advertiser is not part of the protected
scope.
ServiceLocationInternalNetException
Thrown if an error occurs in network communication.
ServiceLocationScopeNotSupportedException
Thrown if the DA is not part of one of the scopes.
ServiceLocationParseException
Thrown if the DA or SA server (if one exists) encounters an
unspecified error.
public abstract void deregister(ServiceURL URL)
throws ServiceLocationException
Guttman, Kempf, Provan Expires 31 May 1998 [Page 45]
Internet Draft Service Location API 30 November 1997
Deregister a service with the service location protocol. This has
the effect of deregistering the service from every language locale
and scope it was registered under.
Parameters:
URL
The service: URL for the service.
Throws:
IllegalArgumentException
Thrown if the parameter is null.
ServiceLocationCharsetNotSupportedException
Thrown if the SA server (if one exists) or DA does not support
the character set encoding set by the net.slp.characterEncoding
property.
ServiceLocationAuthenticationException
Thrown if one or more of the scopes in which the argument
service: URL ia registered are protected and the SLP framework
for the Advertiser is not part of the protected scope.
ServiceLocationInternalNetException
Thrown if an error occurs in network communication.
ServiceLocationInvalidRegistrationException
Thrown if the argument service: URL was not registered.
ServiceLocationParseException
Thrown if the DA or SA server (if one exists) encounters an
unspecified error.
public abstract void
addAttributes(ServiceURL URL,
Vector scopeNames,
Vector attributes)
throws ServiceLocationException
Guttman, Kempf, Provan Expires 31 May 1998 [Page 46]
Internet Draft Service Location API 30 November 1997
Update the registration by adding the given attributes.
Parameters:
URL
The service: URL for the service.
vScopes
The SLP scopes of the service.
attributes
A vector of ServiceLocationAttribute objects to add to the
existing registration.
Throws:
IllegalArgumentException
Thrown if any parameter is null.
ServiceLocationCharsetNotSupportedException
Thrown if the SA server (if one exists) or DA does not support
the character set encoding set by the net.slp.characterEncoding
property.
ServiceLocationAuthenticationException
Thrown if one or more of the scopes are protected and the SLP
framework for the Advertiser is not part of the protected
scope.
ServiceLocationInternalNetException
Thrown if an error occurs in network communication.
ServiceLocationInvalidRegistrationException
Thrown if the type of an attribute value does not match the
type of an existing attribute.
ServiceLocationScopeNotSupportedException
Thrown if the DA is not part of one of the scopes.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 47]
Internet Draft Service Location API 30 November 1997
ServiceLocationParseException
Thrown if the DA or SA server (if one exists) encounters an
unspecified error.
public abstract void
deleteAttributes(ServiceURL URL,
Vector attributeIds)
throws ServiceLocationException
Delete the attributes from a service: URL in all scopes for the
locale with which the Advertiser was created.
Parameters:
URL
The service: URL for the service.
attributeIds
A vector of Strings indicating the id's of the attributes to
remove.
Throws:
IllegalArgumentException
Thrown if any parameter is null.
ServiceLocationCharsetNotSupportedException
Thrown if the SA server (if one exists) or DA does not support
the character set encoding set by the net.slp.characterEncoding
property.
ServiceLocationAuthenticationException
Thrown if one or more of the scopes in which the URL is
registered are protected and the SLP framework for the
Advertiser is not part of the protected scope.
ServiceLocationInternalNetException
Thrown if an error occurs in network communication.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 48]
Internet Draft Service Location API 30 November 1997
ServiceLocationInvalidRegistrationException
Thrown if the URL is not registered or not registered in the
language locale of the Advertiser, if the service: URL has no
attributes, or if there are no attributes matching the tags.
ServiceLocationParseException
Thrown if the DA or SA server (if one exists) encounters an
unspecified error.
5.3.2. Interface Locator
5.3.2.1. Synopsis
public interface Locator
5.3.2.2. Description
The Locator is the UA interface, allowing clients to query the SLP
framework about existing service types, services instances, scopes,
and about the attributes of an existing service instance or service
type. Queries for services and attributes are made in the locale the
Locator was created with, queries for service types and scopes are
independent of locale.
5.3.2.3. Instance Methods
public abstract Locale getLocale()
Return the language locale with which this object was created.
public abstract Vector findScopes()
Returns a vector Strings giving known scope names. The vector
will always have at least one element: "", the empty string, for
unscoped.
public abstract Vector
Guttman, Kempf, Provan Expires 31 May 1998 [Page 49]
Internet Draft Service Location API 30 November 1997
findServiceTypes(String namingAuthority,
String scope)
throws ServiceLocationException
Returns a vector Strings givning known service types for this scope
and naming authority. If no service types are found, an empty vector
is returned. The service type names are returned with the naming
authority included, i.e. as:
service-type "." naming-authority
Parameters:
namingAuthority
The naming authority. Use the empty string, "", for the
default naming authority or "*" for all naming authorities.
scope
The scope name. Use the empty string for no scope.
Throws:
IllegalArgumentException
Thrown if either the scope or the naming authority contain
illegal characters, or if either parameter is null.
ServiceLocationCharsetNotSupportedException
Thrown if the SA or DA does not support the character set
encoding set by the net.slp.characterEncoding property.
ServiceLocationScopeNotSupportedException
Thrown if the DA does not support the scope.
ServiceLocationParseException
Thrown if the DA or SA encounters an unspecified error.
public abstract Vector
findServices(String serviceType,
String namingAuthority,
Guttman, Kempf, Provan Expires 31 May 1998 [Page 50]
Internet Draft Service Location API 30 November 1997
String scope,
String query)
throws ServiceLocationException
Returns a vector of ServiceURL objects for services matching the
query. If no services are found, an empty vector is returned.
Parameters:
serviceType
The SLP service type of the service.
namingAuthority
The naming authority for the type. Use empty string, "", for
default.
scope
The name of the scope. Use empty string for no scope.
query
A string with the SLP query. The query must be
properly formatted according to the rules in Section
5. of [5]. In particular, all escapable characters
in the attribute id's and patterns must be escaped,
and byte array patterns must be in radix-64 [12]
format. The ServiceLocationAttribute.getEscapedId()
and ServiceLocationAttribute.getEscapedValues() methods can
be used to obtain escaped id and value strings for use in
formulating a query. In addition, patterns may use wildcards
as described in [5] to match a range of string attribute
values. An empty string, "", for the query returns all
services having the indicated service type, naming authority,
and scope.
Throws:
IllegalArgumentException
Thrown if any parameter contains illegal characters, or is
null.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 51]
Internet Draft Service Location API 30 November 1997
ServiceLocationCharsetNotSupportedException
Thrown if the SA or DA does not support the character set
encoding set by the net.slp.characterEncoding property.
ServiceLocationLanguageNotSupportedException
Thrown if the net.slp.isMonolingual property is true and the SA
or DA has registrations for another language locale but not for
the language locale of this Locator.
ServiceLocationScopeNotSupportedException
Thrown if the DA does not support the scope.
ServiceLocationParseException
Thrown if the DA or SA encounters an unspecified error or the
query is improperly formatted.
public abstract Vector
findAttributes(ServiceURL URL,
String scope,
Vector attributeIds)
throws ServiceLocationException
For the service: URL and scope, return a Vector of
ServiceLocationAttribute objects whose id's match the String
patterns in the attributeIds Vector. The request is made in the
language locale of the Locator. If no attributes match, an empty
vector is returned.
Parameters:
URL
The service: URL for which the attributes are desired.
scope
The scope. Use empty string for no scope.
attributeIds
A Vector of String patterns identifying the desired attributes.
An empty vector means return all attributes. As described
in [5], Section 12., the patterns may include wildcards to
Guttman, Kempf, Provan Expires 31 May 1998 [Page 52]
Internet Draft Service Location API 30 November 1997
match all prefixes or suffixes. The patterns may include
escapable characters.
Throws:
IllegalArgumentException
Thrown if any parameter is null or the scope name contains
illegal characters.
ServiceLocationCharsetNotSupportedException
Thrown if the SA or DA does not support the character set
encoding set by the net.slp.characterEncoding property.
ServiceLocationLanguageNotSupportedException
Thrown if the net.slp.isMonolingual property is true and the SA
or DA has registrations for another language locale but not for
the language locale of this Locator.
ServiceLocationScopeNotSupportedException
Thrown if the DA does not support the scope.
ServiceLocationParseException
Thrown if the DA or SA encounters an unspecified error.
public abstract Vector
findAttributes(String serviceType,
String namingAuthority,
String scope,
Vector attributeIds)
throws ServiceLocationException
For the type and scope, return a Vector of all ServiceLocationAttribute
objects whose id's match the String patterns in the attributeIds
Vector. The request is made independent of language locale. If no
attributes are found, an empty vector is returned.
Parameters:
serviceType
The service type.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 53]
Internet Draft Service Location API 30 November 1997
namingAuthority
The naming authority for the type. Use the empty string, "",
for default.
scope
The scope. Use empty string for no scope.
attributeIds
A Vector of String patterns identifying the desired attributes.
An empty vector means return all attributes. As described
in [5], Section 12., the patterns may include wildcards to
match all prefixes or suffixes. The patterns may include
escapable characters.
Throws:
IllegalArgumentException
Thrown if any parameter is null or contains illegal characters.
ServiceLocationCharsetNotSupportedException
Thrown if the SA or DA does not support the character set
encoding set by the net.slp.characterEncoding property.
ServiceLocationScopeNotSupportedException
Thrown if the DA does not support the scope.
ServiceLocationParseException
Thrown if the DA or SA encounters an unspecified error.
5.3.3. Interface TemplateRegistry
5.3.3.1. Synopsis
public interface TemplateRegistry
Guttman, Kempf, Provan Expires 31 May 1998 [Page 54]
Internet Draft Service Location API 30 November 1997
5.3.3.2. Description
The TemplateRegistry interface provides access to service location
templates [11]. Classes implementing TemplateRegistry register and
unregister service templates, look up template URL's based on the
service type name, and return attribute verifiers for verifying that
vectors of attributes to be used in registering a service instance
match the service's template, and for introspection on the template
definition. Note that the Advertiser is not required to verify
attributes before registering.
5.3.3.3. Instance Methods
public abstract void
registerServiceTemplate(String serviceType,
String documentURL,
String version,
Locale locale,
String description,
String urlPathRules)
throws ServiceLocationException
Register the service template with the template registry.
Parameters:
serviceType
The service type name, including naming authority.
documentURL
The URL of the template document.
version
The version number of template document.
locale
The language locale of the template.
description
Help text describing the service.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 55]
Internet Draft Service Location API 30 November 1997
urlPathRules
The ABNF grammer describing the service: URL's url part.
Throws:
InvalidArgumentException
Thrown if any parameter is null, if the service type name has
illegal characters, or if the document URL has an invalid
format.
ServiceLocationInvalidRegistrationException
Thrown if the template is already registered or the
registration fails.
public abstract void
deregisterServiceTemplate(String serviceType)
throws ServiceLocationException
Deregister the template for service type.
Parameters:
serviceType
The service type name, including naming authority.
Throws:
IllegalArgumentException
Thrown if the parameter is null or contains illegal characters.
ServiceLocationInvalidRegistrationException
Thrown if the template is not registered.
public abstract
ServiceLocationAttributeVerifier
attributeVerifier(String serviceType)
throws ServiceLocationException
Guttman, Kempf, Provan Expires 31 May 1998 [Page 56]
Internet Draft Service Location API 30 November 1997
Returns an attribute verifier for the service type. The attribute
verifier can be used to verify that attributes for registration match
the template, and can for introspection on the template definition.
Parameters:
serviceType
A String containing the name of the service type.
Throws:
IllegalArgumentException
Thrown if the parameter is null or if the service type contains
illegal characters.
ServiceLocationParseException
Thrown if any syntax errors are encountered during parsing of
service's template document. The message describes the error
in more detail
5.4. The Service Location Manager
5.4.1. Class ServiceLocationManager
5.4.1.1. Synopsis
public class ServiceLocationManager
extends Object
5.4.1.2. Description
The ServiceLocationManager manages access to the connection with the
service location framework. Clients obtain the Locator, Advertiser,
and TemplateRegistry objects for UA, SA, and service template access
from the ServiceLocationManager.
5.4.1.3. Class Methods
public static Locator
getLocator(Locale locale)
Guttman, Kempf, Provan Expires 31 May 1998 [Page 57]
Internet Draft Service Location API 30 November 1997
throws ServiceLocationException
Return a Locator object for the given language Locale. If the
implementation does not support UA functionality, returns null.
Parameters:
locale
The language locale of the Locator. The default locale is uses
if null.
Throws:
ServiceLocationInternalSystemException
Thrown if any internal errors occur.
ServiceLocationInitNetException
Thrown if the network connection to multicast or DA unicast
cannot be initiated.
ServiceLocationInternalNetException
Thrown if errors occur in network communication.
public static Advertiser
getAdvertiser(Locale locale)
throws ServiceLocationException
Return an Advertiser object for the given language locale. If the
implementation does not support SA functionality, returns null.
Throws:
ServiceLocationInternalSystemException
Thrown if any internal errors occur.
ServiceLocationInitNetException
Thrown if the network connection to multicast or DA unicast
cannot be initiated.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 58]
Internet Draft Service Location API 30 November 1997
ServiceLocationInternalNetException
Thrown if errors occur in network communication.
public static TemplateRegistry
getTemplateRegistry()
throws ServiceLocationException
Return a TemplateRegistry object for programmatic access to service
location type template documents. If the implementation does not
support template registry functionality, returns null.
Throws:
ServiceLocationInternalSystemException
Thrown if the root template document can't be found.
5.5. Service Type Template Introspection
5.5.1. Interface ServiceLocationAttributeVerifier
5.5.1.1. Synopsis
public interface
ServiceLocationAttributeVerifier
5.5.1.2. Description
The ServiceLocationAttributeVerifier provides access to service type
templates. Classes implementing this interface parse SLP template
definitions, provide information on attribute definitions for
service types, and verify whether a ServiceLocationAttribute object
matches a template for a particular service type. Clients obtain
ServiceLocationAttributeVerifier objects for specific SLP service
types through the TemplateRegistry.
5.5.1.3. Instance Methods
public abstract String getServiceType()
Guttman, Kempf, Provan Expires 31 May 1998 [Page 59]
Internet Draft Service Location API 30 November 1997
Returns the SLP service type for which this is the verifier.
public abstract Vector
getTemplateAttributeDescriptors()
Returns a Vector of ServiceLocationAttributeDescriptor objects
describing the template service type attributes. The template
service type attributes are:
service-type
The SLP service type name.
version
The version number of the template.
language
The ISO-639 [10] language locale of the template.
description
A natural language description of the service in the language
of the language locale.
url-syntax
An ABNF [3] description for the service part of the service
type's service: URL.
public abstract Vector
getTemplateAttributes()
Returns a Vector of ServiceLocationAttribute objects for the template
attributes of this service type. The template attributes are listed
above. The ServiceLocationAttribute objects in this vector will have
the actual values of the template attributes.
public abstract Dictionary
getAttributeDescriptors()
Guttman, Kempf, Provan Expires 31 May 1998 [Page 60]
Internet Draft Service Location API 30 November 1997
Returns a Dictionary allowing introspection on the attribute
definition in the service type template. The Dictionary has the
attribute id's as the keys and ServiceLocationAttributeDescriptor
objects for the attributes as values. This method is primarily
for GUI tools to display attribute information. Programmatic
verification of attributes should use the verifyAttribute() method.
Note that small memory implementations may want to implement the
Dictionary so that attributes are parsed on demand rather than at
creation time.
public abstract void
verifyAttribute(
ServiceLocationAttribute attribute)
throws ServiceLocationParseException
Verify that the attribute matches the template definition.
Parameters:
attribute
The ServiceLocationAttribute object to be verified.
Throws:
ServiceLocationParseException
Thrown if the attribute does not match a template definition.
The message contains information on the attribute name and
problem.
public abstract void
verifyRegistration(
Vector attributeVector)
throws ServiceLocationParseException
Verify that the Vector of ServiceLocationAttribute objects matches
the template for this service type. The vector must contain all the
required attributes, and all attributes must match their template
definitions.
Parameters:
Guttman, Kempf, Provan Expires 31 May 1998 [Page 61]
Internet Draft Service Location API 30 November 1997
attributeVector
A Vector of ServiceLocationAttribute objects for the
registration.
Throws:
ServiceLocationParseException
Thrown if the attribute vector does not contain the required
attributes in the template, if any of the attributes do not
match their template definition, or if the vector contains
attributes not defined in the template.
5.5.2. Interface ServiceLocationAttributeDescriptor
5.5.2.1. Synopsis
public interface
ServiceLocationAttributeDescriptor
5.5.2.2. Description
The ServiceLocationAttributeDescriptor interface provides
introspection on a template attribute defintion. Classes
implementing the ServiceLocationAttributeDescriptor interface return
information on a particular service location attribute definition
from the service type template. This information is primarily for
GUI tools. Programmatic attribute verification should be done
through the ServiceLocationAttributeVerifier.
5.5.2.3. Instance Methods
public abstract String getId()
Return a String containing the attribute's id.
public abstract String getValueType()
Guttman, Kempf, Provan Expires 31 May 1998 [Page 62]
Internet Draft Service Location API 30 November 1997
Return a String containing the fully package-qualified Java type of
the attribute. SLP types are translated into Java types as follows:
STRING
"java.lang.String"
INTEGER
"java.lang.Integer"
BOOLEAN
"java.lang.Boolean"
OPAQUE
"[B" (i.e. array of byte, byte[])
KEYWORD
empty string, ""
public abstract String getDescription()
Return a String containing the attribute's help text.
public abstract Enumeration
getAllowedValues()
Return an Enumeration of allowed values for the attribute type.
For keyword attributes returns null. For no allowed values
(i.e. unrestricted) returns an empty Enumeration. Small memory
implementations may want to parse values on demand rather than at the
time the descriptor is created.
public abstract Enumeration
getDefaultValues()
Return an Enumeration of default values for the attribute type.
For keyword attributes returns null. For no allowed values
(i.e. unrestricted) returns an empty Enumeration. Small memory
Guttman, Kempf, Provan Expires 31 May 1998 [Page 63]
Internet Draft Service Location API 30 November 1997
implementations may want to parse values on demand rather than at the
time the descriptor is created.
public abstract boolean getIsMultivalued()
Returns true if the "M" flag is set.
public abstract boolean getIsOptional()
Returns true if the "O"" flag is set.
public abstract boolean
getRequiresExplicitMatch()
Returns true if the "X"" flag is set.
public abstract boolean getIsLiteral()
Returns true if the "L" flag is set.
public abstract boolean getIsKeyword()
Returns true if the attribute is a keyword attribute.
5.6. Exceptions
5.6.1. Class ServiceLocationException
5.6.1.1. Synopsis
abstract public class
ServiceLocationException
extends Exception
Guttman, Kempf, Provan Expires 31 May 1998 [Page 64]
Internet Draft Service Location API 30 November 1997
5.6.1.2. Description
The ServiceLocationException class is the superclass for all SLP
exceptions.
5.6.2. Class ServiceLocationAuthenticationException
5.6.2.1. Synopsis
public class
ServiceLocationAuthenticationException
extends ServiceLocationException
5.6.2.2. Description
The ServiceLocationAuthenticationException class implements the
AUTHENTICATION_ABSENT and AUTHENTICATION_FAILED error codes from
Section 23 of [5].
5.6.3. Class ServiceLocationCharsetNotUnderstoodException
5.6.3.1. Synopsis
public class
ServiceLocationCharsetNotUnderstoodException
extends ServiceLocationException
5.6.3.2. Description
The ServiceLocationCharsetNotUnderstoodException class implements the
CHARSET_NOT_UNDERSTOOD error code from Section 23 of [5].
5.6.4. Class ServiceLocationLanguageNotSupportedException
5.6.4.1. Synopsis
public class
ServiceLocationLanguageNotSupportedException
extends ServiceLocationException
Guttman, Kempf, Provan Expires 31 May 1998 [Page 65]
Internet Draft Service Location API 30 November 1997
5.6.4.2. Description
The ServiceLocationLanguageNotSupportedException class implements the
LANGUAGE_NOT_SUPPORTED error code from Section 23 of [5].
5.6.5. Class ServiceLocationScopeNotSupportedException
5.6.5.1. Synopsis
public class
ServiceLocationScopeNotSupportedException
extends ServiceLocationException
5.6.5.2. Description
The ServiceLocationScopeNotSupportedException class implements the
SCOPE_NOT_SUPPORTED error code from Section 23 of [5].
5.6.6. Class ServiceLocationParseException
5.6.6.1. Synopsis
public class
ServiceLocationParseException
extends ServiceLocationException
5.6.6.2. Description
The ServiceLocationParseException class implements the
PROTOCOL_PARSE_ERROR error code from Section 23 of [5].
PROTOCOL_PARSE_ERROR is also returned by DA's and SA's when
unspecified internal errors occur on the server side.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 66]
Internet Draft Service Location API 30 November 1997
5.6.7. Class ServiceLocationInvalidRegistrationException
5.6.7.1. Synopsis
public class
ServiceLocationInvalidRegistrationException
extends ServiceLocationException
5.6.7.2. Description
The ServiceLocationInvalidRegistrationException class implements the
INVALID_REGISTRATION error code from Section 23 of [5].
5.6.8. Class ServiceLocationInternalSystemException
5.6.8.1. Synopsis
public class
ServiceLocationInternalSystemException
extends ServiceLocationException
5.6.8.2. Description
The ServiceLocationInternalSystemException is thrown when internal
errors are encountered on the client, i.e SA and UA, side.
5.6.9. Class ServiceLocationInternalNetException
5.6.9.1. Synopsis
public class
ServiceLocationInternalNetException
extends ServiceLocationException
5.6.9.2. Description
The ServiceLocationInternalNetException is thrown when any network
error occurs after initialization.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 67]
Internet Draft Service Location API 30 November 1997
5.6.10. Class ServiceLocationInitNetException
5.6.10.1. Synopsis
public class
ServiceLocationInitNetException
extends ServiceLocationException
5.6.10.2. Description
The ServiceLocationInitNetException is thrown when an error occurs in
intializing a network connection.
5.7. Implementation Notes
5.7.1. Client Side Syntax Checking
The syntax of scope names, service type names, naming authority
names, and service: URL's is described in [5] and [11]. The various
methods and classes taking String parameters for these entities
should type check the parameters for syntax errors on the client
side, and throw an IllegalArgumentException if an error occurs. In
addition, character escaping should be implemented before network
transmission for escapable characters in attribute id's and String
values. This reduces the number of error messages transmitted. The
ServiceLocationAttribute class provides methods for obtaining escaped
attribute id and value strings to facilitate query construction.
5.7.2. Character Set Encoding
Java provides support for most IANA character encodings [6]. In
addition to the underlying Java support, however, implementations are
required to provide escaping and unescaping of escapable characters
in attribute values, patterns, and id's. Escaping a character
requires that the character to be translated into a numerical code
in the on the wire encoding. Similarly, unescaping requires the
numerical code to be translated back into the Unicode character
used within the Java virtual machine. Implementations are required
to support "US-ASCII" as the default encoding, and, additionally,
"LATIN1", "Unicode"', and "UTF8". Other encodings may be supported.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 68]
Internet Draft Service Location API 30 November 1997
5.7.3. Language Locale Handling
The Locator and Advertiser interfaces are created with a Locale
parameter. The language locale with which these objects are created
is used in all SLP requests issued through the object. If the Locale
parameter is null, the default is used. The default locale is
determined by, first, checking the net.slp.locale System property.
If that is unset, then the default Java locale is used. The locale
is the only SLP system property for which an API operation override
is provided.
5.7.4. Setting SLP System Properties
SLP system properties that are originally set in the configuration
file can be overridden programmatically in API clients by simply
invoking the System.getProperties() operation to get a copy of the
system properties, modifying or adding the SLP property in question,
then using System.setProperties() to set the properties to the
modified Property object. Errors are checked when the property
is used and, as with parsing the configuration file, are logged.
Program execution continues without interruption by substituting the
default for the erroneous parameter. In general, individual agents
should rarely be required to override these properties, since they
reflect properties of the SLP network which are not of concern to
individual agents. If changes are required, system administrators
should modify the configuration file.
5.7.5. Implementing register() and addAttributes()
Because the underlying SLP protocol has no separate message for
updating a registration, it is not possible to implement the
Advertiser.register() and Advertiser.addAttributes() operations
disjointly without caching or performing an additional protocol
message. The ``natural semantics'' are that a Advertiser.register()
causes the advertisement to be replaced by the new registration,
while Advertiser.addAttributes() causes attributes to be added to
an existing registration, or ignored if there is no registration.
However, the service registration message in SLP causes an update
if the advertisement already exists, otherwise it registers the new
advertisment. Only upon return does the SA learn, via the message
header ``fresh'' bit, whether the advertisement was an update or a
new registration.
An implementation can use either one of two algorithms to implement
the natural semantics for these operations:
Guttman, Kempf, Provan Expires 31 May 1998 [Page 69]
Internet Draft Service Location API 30 November 1997
Issue a protocol request prior to the service registration to
obtain information on the current status of the advertisement.
Cache registrations and use the cached information to determine
the current status of the advertisement.
The first solution would require issuing an SLP service request prior
to the register request and, if the service is registered, issuing
a SLP deregister request. The second solution would use the cached
registration determine whether the advertisement is registered and to
issue the deregister request, eliminating one network operation.
For the Advertiser.addAttributes() operation, the first solution
would require issuing an SLP attribute request prior to the register
request to determine if the advertisement is registered, and only
issuing the register request if so. The second solution would use
the cached information to determine whether the advertisment is
registered, prior to issuing the register request, again eliminating
one network operation.
Implementations may support these semantics, but because of the
additional memory or network resource burden, are not required to do
so.
5.7.6. Exceptions
Each of the error codes in [5] are mapped into a subclass
of ServiceLocationException, with the exception that the
two authentication error codes, AUTHENTICATION_ABSENT and
AUTHENTICATION_FAILED, are reported back to the client as a
single exception, ServiceLocationAuthenticationException.
Additional, client side exceptions that involve internal failures,
network failures, or failures in initiating a network connection
are reported through the ServiceLocationInternalSystemException,
ServiceLocationInternalNetException, and ServiceLocationInitNetException.
When parameters are checked for validity (such as not being null) or
their syntax is checked, an error results in the RuntimeException
subclass IllegalArgumentException being thrown. Clients of the
API are reminded that IllegalArgumentException is unchecked by the
compiler, and so they should be careful to include try/catch blocks
for it if the relevent parameters could be erroneous.
5.7.7. Multithreading
Thread-safe and thread-hot operation are relatively easy to
achieve in Java. By simply making each method in the classes
implementing the Locator and Advertiser interfaces synchronized, and
Guttman, Kempf, Provan Expires 31 May 1998 [Page 70]
Internet Draft Service Location API 30 November 1997
by synchronizing access to any shared data structures within the
class the Locator and Advertiser interfaces are both thread-safe and
thread-hot.
Similarly, automatic registration refreshing in the SA can be
achieved by having a thread running the background that periodically
refreshes all registrations whose ServiceURL lifetime parameter is
ServiceURL.LIFETIME_PERMANENT. When Advertiser.register() is called
with such a URL, the Advertiser implementation can record the URL for
future reference.
5.7.8. Return of Unscoped Services
Because of a peculiarity in SLP service request semantics (see
Section 5. in [5]), a service request for which a scope is specified
returns both services in that scope and unscoped services. There
is no way to disallow return of unscoped services. Filtering out
unwanted services is unfortunately time consuming, since the UA would
have to send another service request for unscoped services, then
remove matching items from the first return. Implementations may try
to assure that the Locator interface just returns services in the
scope for which the request was made, but are not required to do so.
5.7.9. Modular Implementations
While, at first glance, the API may look rather heavyweight, the
design has been carefully arranged so that modular implementations
which provide only SA, only UA, or only service template access
capability, or any combination of the three, are possible. Because
the objects returned from the ServiceLocationManager.getLocator(),
ServiceLocationManager.getAdvertiser(), and
ServiceLocationManager.getTemplateRegistry() operations are
interfaces, and because most objects returned through those
interfaces are either in the set of base data structures or
are, themselves, interfaces, an implementation is free to omit a
particular capability. The classes implementing the capability can
be dynamically linked when needed, or for particularly low weight
implementations, the ServiceLocationManager access method for the
missing object can simply return null. API clients are encouraged
to check for such a contingency, and to signal an exception if it
occurs. In this way, the API implementation can be taylored for the
particular memory requirements at hand.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 71]
Internet Draft Service Location API 30 November 1997
5.8. Examples
In this example, a printer server advertises its availability to
clients. Additionally, the server advertises a service template for
use by client software in validating service requests:
//Get the Advertiser and TemplateRegistry.
Advertiser adv = null;
TemplateRegistry tr = null
try {
adv =
ServiceLocationManager.getAdvertiser("en");
tr =
ServiceLocationManager.getTemplateRegistry();
} catch( ServiceLocationException ex ) {
//Deal with error.
}
if( adv == null ) {
//Serious error as printer can't be registered
// if the implementation doesn't support SA
// functionality.
}
//Get the scopes in which we are supposed to
// register.
Vector scopes = adv.findScopes();
//Get the printer's attributes, from a file or
// otherwise. We assume that the attributes
// conform to the template, otherwise, we
// could register the template here and verify
// them.
Vector attributes = getPrinterAttributes();
//Create the service: URL for the printer.
ServiceURL printerURL =
Guttman, Kempf, Provan Expires 31 May 1998 [Page 72]
Internet Draft Service Location API 30 November 1997
new ServiceURL(
"service:printer:lpr://printshop/color2",
ServiceURL.LIFETIME_PERMANENT);
try {
//Register the printer all scopes.
adv.register(printerURL,
scopes,
attributes);
//If the template registry is available,
// register the printer's template.
if( tr != null ) {
tr.registerServiceTemplate(
"printer",
"http://shop.arv/printer/printer-lpr.slp",
"1.0",
"en",
"This template describes the lpr "+
"concrete printer type.",
"\"lpr://\" machine \"/\" queue");
}
} catch( ServiceLocationException ex ) {
//Deal with error.
}
Suppose a client is looking for color printer. The following code
might be used to issue a request for printer service: URL's:
Locator loc = null;
TemplateRegistry tr = null;
try {
loc =
ServiceLocationManager.getLocator("en");
tr =
ServiceLocationManager.getTemplateRegistry();
} catch( ServiceLocationException ex ) {
Guttman, Kempf, Provan Expires 31 May 1998 [Page 73]
Internet Draft Service Location API 30 November 1997
//Deal with error.
}
if( loc == null ) {
//Serious error as client can't be located
// if the implementation doesn't support
// UA functionality.
}
//We want a color printer that does CMYK
// and prints at least 600 dpi.
Vector attributes = new Vector();
Vector values = new Vector();
values.addElement("CMYK");
attributes.addElement(
new ServiceLocationAttribute("marker-type",
values));
values = new Vector();
values.addElement(new Integer(600));
attributes.addElement(
new ServiceLocationAttribute("resolution",
values));
//Check the attributes to be sure they
// match.
if( tr != null ) {
ServiceLocationAttributeVerifier ver = null;
try {
ver = tr.attributeVerifier("printer");
ver.verifyAttribute(attributes.elementAt(0));
ver.verifyAttribute(attributes.elementAt(1));
} catch( ServiceLocationException ex ) {
//Deal with error.
}
Guttman, Kempf, Provan Expires 31 May 1998 [Page 74]
Internet Draft Service Location API 30 November 1997
}
//Get scopes.
Vector scopes = loc.findScopes();
//Get services. Any scope will do.
Vector services = null;
String scope = (String)scopes.elementAt(0);
try {
services =
loc.findServices("printer",,attributes);
} catch {
//Deal with error.
}
//Printers can now be used.
6. Internationalization Considerations
6.1. service: URL
The service: URL itself must be encoded using the rules set forth
in [2]. The character set encoding is limited to specific ranges
within the US-ASCII character set [1].
The attribute information associated with the service: URL may be
expressed in any character set, and in any language. See [11] for
attribute internationalization guidelines.
6.2. Character Set Identification and Use
The way of identifying the character set used is the IANA Character
Set registry MIB Enum value (in C) or IANA character set name (in
Java). [6]
It can be assumed that US-ASCII [1] will be supported. Programs
which register or request information using other character sets must
be prepared for the possibility that the SLP framework is not capable
Guttman, Kempf, Provan Expires 31 May 1998 [Page 75]
Internet Draft Service Location API 30 November 1997
of supporting it. In this case, they should fall back to US-ASCII if
possible.
The service's identity is independent of the character set encoding
used to register it. A service can be registered with one character
set encoding, queried in another, and deregister in a third as long
as all three encodings map to the same URL. Furthermore, a different
character set may be used in packets transmitted to satisfy the
operation.
7. Security Considerations
SLP will make use of an existing host based authentication framework
once it becomes available as an Internet Standard. [7]
In the absence of this, it is extremely easy for anyone to register
any service with Service Location. SLP does not authenticate the
source of service advertisements, either at the DA or when the UA
receives it.
For this reason, use of SLP on open networks, such as the Internet,
should be avoided. A DA may be provided on an open network with
registration capabilities disabled; but this is of limited utility
since a UA would not be able to distinguish it from a DA full of
impersonations.
For this reason, SLP should only be used in 'private' networks, as
those behind firewalls where users are expected to perform in a
responsible manner.
SLP is neutral to the protocols clients and servers use between
themselves. Strong bidirectional authentication at higher levels
(ie. transport level: "The SSL Protocol, Version 3" [9] or
application level: "Generic Security Service Application Program
Interface" [8]) would obviate the risk of masquerading by an
adversary using SLP.
An adversary could delete valid service advertisements and deny UAs
knowledge of existing services.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 76]
Internet Draft Service Location API 30 November 1997
References
[1] ANSI. Coded Character Set -- 7-bit American Standard code for
Information Interchange. X3.4-1986, 1986.
[2] T. Berners-Lee, R. Fielding, and L. Masinter. Uniform Resource
Locators (URL): Generic Syntax and Semantics. RFC1738 as
amended by RFC1808 and updated by draft-fielding-url-syntax-05.txt,
May 1997. (work in progress).
[3] D. Crocker and P Overell. Augmented BNF for Syntax
Specifications: ABNF. draft-ietf-drums-abnf-04.txt, September
1997. (work in progress).
[4] Geneva ISO. Code for the representation of names of languages.
ISO 639:1988 (E/F), 1988.
[5] J. Veizades, E. Guttman, C. Perkins, and S. Kaplan. Service
Location Protocol. RFC 2165, July 1997.
[6] IANA IANA Character Set Registry
<URL:http://www.isi.edu/in-notes/iana/assignments/character-sets>
[7] R. Atkinson Security Architecture for the Internet RFC 1825
July 1995
[8] J. Linn Generic Security Application Program Interface, Version
2 A work in progress November 1996
[9] A. Freier, P. Karlton, P. Kocher The SSL Protocol, Version 3.0
A work in progress November 1996
[10] Geneva ISO Code for the representation of names of languages
ISO 639:1998 (E/F) 1998
[11] E. Guttman, C. Perkins, J. Kempf Service Templates and service:
Schemes A work in progress November 1997
[12] N. Borenstein and N. Freed. MIME (Multipurpose Internet Mail
Extensions) Part One: Mechanisms for Specifying and Describing
the Format of Internet Message Bodies. RFC 1521, September
1993.
Guttman, Kempf, Provan Expires 31 May 1998 [Page 77]
Internet Draft Service Location API 30 November 1997
Authors' Addresses
Questions about this memo can be directed to:
Erik Guttman James Kempf Don Provan
Sun Microsystems Sun Microsystems Novell, Inc.
Bahnstr. 2 901 San Antonio Rd. 2180 Fortune Drive
74915 Waibstadt Palo Alto, CA, 94303 San Jose, CA, 94303
Germany USA USA
+49 7263 911484 1 650 786 5890 1 408 577 8440
1 650 786 6445 (fax) donp@novell.com
erik.guttman@sun.com james.kempf@sun.com
Guttman, Kempf, Provan Expires 31 May 1998 [Page 78]