Service Location Working Group Erik Guttman
Internet Draft Sun Microsystems, Inc.
Expires in six months Don Provan
Novell, Inc.
An API for Service Location
<draft-ietf-svrloc-api-01.txt>
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 (Europe), munnari.oz.au (Pacific Rim),
ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast).
Abstract
The Service Location Protocol coupled with the Service Location API
provide a new way for clients to dynamically discovery network
services. It is simple to offer highly available services which
require no user configuration or communication with network
administrators prior to use. The document includes examples and
applications.
Client software modified to use Service Location can make very simple
requests to find service by type or by characteristic. The latter
capability allows the client to choose intelligently between services
of the same type. Service software modified to use Service Location
may dynamically advertise its characteristics and existence.
Remaining Issues:
1. Should query results have their own types, or is the current
scheme using Result alright (for the C interface)?
2. Should the SLP authentication framework be exposed at the
API level? This could allow programs to do their own
Guttman,Provan [Page 1]
Internet Draft An API for Service Location 24 March 1997
cryptographic key assignment, to require authentication,
etc.
3. Replies to SLP requests may be very large. Should there
be a mechanism to allow iterative return of results? This
way all 10000 attributes would not have to be returned at
once, for example. An application could obtain them 100
at a time, etc.
4. Review the adequacy of the SLP Config File format presented
in this draft.
5. Is the language precise enough about what to do with multiple
replies? (Some may contain error messages, others are OK...)
Table of Contents
1. Introduction
2. Glossary
3. Interfaces
3.1. SL_Open
3.2. SL_Close
3.3. SL_Register
3.4. SL_DeRegister
3.5. SL_GetScopes
3.6. SL_GetServiceTypes
3.7. SL_GetService
3.8. SL_GetAttrs
3.9. SL_Free
3.10. SL_Binary2Opaque
4. API programming notes
4.1. Multithreading Issues
4.2. Nonstandard Service Types are easy
4.3. Typical Client Scenarios
4.4. Top level information
4.5. Example applications of SLP
4.5.1. Coarse dynamic load balancing
4.5.2. Mobile user finds the nearest printer
4.5.3. Providing highly available services
5. API implementation issues
6. Language specific API specification and examples
6.1. SLP API C bindings
6.1.1. Header file definitions
6.1.2. Interface clarification
6.1.3. Examples
6.2. SLP API Java bindings
6.2.1. Class definitions
6.2.2. Examples
6.3. Syntax for string parameters
6.3.1. Character Escapes
Guttman,Provan [Page 2]
Internet Draft An API for Service Location 24 March 1997
6.3.2. String Matching
6.3.3. Query Syntax
6.3.3.1. List Query Syntax
6.3.3.2. General Query Syntax
6.3.3.3. White Space
6.3.4. Attribute Registration List
6.3.5. Attribute Deregistration List
6.3.6. Attribute Selection List Syntax
6.4. Configuration File Format
7. Interpretation of SLP error values
8. Security Considerations
9. Internationalization Considerations
9.1. Character Set identification and use
9.2. Language identification and translation
10. Bibliography
11. Author's Address
1. Introduction
The Service Location API allows client and service programs to
be modified in a very simple manner to provide dynamic service
discovery and selection.
The underlying protocol makes use of strings extensively, as
does the interface. String syntax for the List Query, General
Query, Attribute Deregistration List and Attribute Registration
List and Attribute Filter List are defined below, in the
appropriate sections.
The API bindings are given in C and Java. The semantics are
discussed in a language and implementation neutral way, with
these details left to later sections.
Applications which are modified to use this API will be
source compatible with different SLP framework implementations.
2. Glossary
Service Location Protocol (SLP)
The underlying protocol allowing dynamic and scalable
service discovery. This protocol is specified in the Service
Location Protocol [SLP].
SLP framework
When a 'Service Location framework' is mentioned, it refers
to all existing SLP agents in the network, the SLP implementation
and interface implementation; ie. whatever provides the SLP
functionality to user level programs. The SLP framework is
transparent to applications using the SLP API, which is to say
Guttman,Provan [Page 3]
Internet Draft An API for Service Location 24 March 1997
they do not need to know whether there are DAs, whether DHCP
is being used, and so on.
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
direct requests to DAs when they exist automatically when
they exist. In their absence, 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.
When a service 'makes' a service advertisement, it uses the
SL_Register API. This distributes the service advertisements
to Directory Agents and in the SLP framework.
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.
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.
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. Each Service Type is identified by a string
(usually the same name as the protocol used to deliver the
Guttman,Provan [Page 4]
Internet Draft An API for Service Location 24 March 1997
service.) See "The service: URL Scheme" [SRV].
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. Scopes SHOULD be used
only when there are DAs assigned a scope, see section 3.5
below.
Protected Scope
A Protected Scope is a Scope for which SAs have cryptographic
keying material sufficient to provide a digitial signature
over service URL and attributes which are registered or
deregistered. A DA will reject SA registrations and
deregistrations for protected scopes for which the digital
signature is absent or fails to show the SA belongs to the
protected Scope. Similarly, UAs may verify the signatures
for URLs and Attributes (if they request ALL attributes) to
determine if the service registration is from the protected
scope. This gives the UA confidence that the Service can
be trusted to be what it purports to be.
Closure
The set of attributes supported by all the services in a
network of a particular type. For instance, the collected
attributes of all printers may be obtained. Closures are
used to discover the range of possible values for services.
Service queries are constructed by selecting combinations
of desirable characteristics from this range.
Naming Authority (NA)
This is a 'suffix' to the service type string. It completely
changes the meaning of the service type. NAs SHOULD only be
used for private definitions of well known Service Types and
experimental Service Type extensions. The default NA is
"IANA", which may be omitted.
3. Interfaces
Of the interfaces listed below, three are for use only in a C API:
SL_Open, SL_Close and SL_Free. The first two interfaces are
unnecessary in an object oriented interface, as the object
initialization and finalization code will perform all the needed
resource allocation and freeing. Further, the object providing SLP
interfaces will encapsulate preference variables. SL_Free is
Guttman,Provan [Page 5]
Internet Draft An API for Service Location 24 March 1997
included solely as a convenience, for freeing Result data structures.
In an object-oriented language, resource freeing will be handled by
the result objects themselves.
The C API requires the use of a SL_SrvHandle, which is created by
SL_Open and passed into each interface. The analogous entity for the
Java API is the ServiceLocator object which encapsulates all the
information and functionality that the SL_SrvHandle provides. For
Java interface implementors: The semantics of SL_Open and SL_Close
must be followed even if SL_SrvHandles are not required.
Note that proper use of Scopes is critical for correct and scalable
use of Service Location. The important notes about the use of Scopes
are included in section 3.5, below.
3.1. SL_Open
This interface is used to create a "SL_SrvHandle", which encapsulates
the program's default settings set by this call.
SL_Open may also be used to modify the settings associated with an
existing SL_SrvHandle. SL_Open must be used to generate a
SL_SrvHandle before any other API functions are used: The library
should be initialized at this point.
The settings which are configurable by SL_Open determine how service
requests will be issued. They include the Language tag, character
set, the maximum time to wait for a response, and whether to "get all
services" or just "return the first one found." These settings apply
only to service requests. Registrations and deregistrations have
parameters to pass this information explicitly.
The SL_SrvHandle is entirely implementation dependent. It is a
simple mechanism which allows instrumentation, resource tracking and
avoidance of global state. The SL_SrvHandle will also allow the API
implementation to refer to some synchronization state, to provide the
synchronous and sequential access semantics described in Section 4.1.
3.2. SL_Close
This interface closes and frees all resources associated with the
SL_SrvHandle. It sets the SL_SrvHandle to NULL. When the last
SL_SrvHandle is closed, the library frees all its resources.
3.3. SL_Register
The service supplies a service: URL, and possibly service attributes.
The attributes to use, their defaults and interpretation, are all
given in the Service Type template. The service also specifies the
Lifetime of the service (how long it can be cached), as well as the
Language tag and character set used.
Guttman,Provan [Page 6]
Internet Draft An API for Service Location 24 March 1997
A call to SL_Register with a URL which has already been registered
will be an 'update'. It will replace the attributes previously
registered, if the update contains attributes of the same name and
language. For example: If the first registration has attributes
"(A=1),(B=2),(C=3)"
and the subsequent registration has attributes
"(C=30),(D=40)"
the registration will end up with
"(A=1),(B=2),(C=30),(D=40)".
An Attribute Registration list string is used for registration. The
above are examples of such strings.
Service advertisements may be made multiple times for the same URL,
in different languages. A service program may provide different
translations of the services offered in this way. For example, the
service could be registered with service attributes translated to
English, Russian and Arabic, with the appropriate character sets.
The same service: URL may now be obtained by users with different
language skills.
A service registered without a scope may only be available from DAs
which have not been configured with any scopes. UAs must explicitly
request services which are unscoped. For these reasons, it is
highly recommended that scopes be used if they have been defined for
a given site. A service is registered in a scope by including a
scope attribute. For instance, if a service is in scope
ADMINISTRATION and WESTERN CAMPUS, the following attribute is
registered:
"(SCOPE=ADMINISTRATION,WESTERN CAMPUS)"
The iLifetime parameter is the time, in seconds, that the service
should be maintained in caches. In other words, this parameter
supplies the SA with the value to use in the lifetime field of URL
block. The SA is responsible for refreshing the service before the
lifetime expires. It can take any value from 0-65535 (seconds).
The values zero (SL_LIFETIME_NONE) and 0xFFFF (SL_LIFETIME_DEFAULT)
are reserved. SL_LIFETIME_NONE indicates the API implementation must
reregister the advertisement, so that it will be continuously
available. SL_LIFETIME DEFAULT will use CONFIG_INTERVAL_1 from the
SLP specification as the lifetime.
3.4. SL_DeRegister
Guttman,Provan [Page 7]
Internet Draft An API for Service Location 24 March 1997
The service: URL of the service to deregister must be provided. If
this is the only information provided, the service advertisement will
be deregistered in every language and character set it has been
registered in.
If a Language tag, character set and Attribute Deregistration List
are provided the attributes indicated by the attribute tags in the
Deregistration list will be removed from the service advertisement.
3.5. SL_GetScopes
This 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. The order in which the scopes
are returned indicates the order of preference: The first scope in
the Scope array should be prefered to the second, etc.
Scopes which are not obtained from DAs, DHCP or static configuration
MUST NOT be returned. It is possible that a SA advertises a service
in such a scope, but not at all recommended. SL_GetScopes must not
return scopes which are present only in advertisements from SAs and
unscoped DAs. The Scope list MUST represent only scoped DAs and the
configuration obtained from DHCP and static configuration files.
UAs SHOULD use a scope obtained from SL_GetScopes in requests
whenever possible. If this Scope is omitted, scoped services
information will not be returned. If there are no scoped DAs, UAs
SHOULD NOT include a scope string in requests and SAs SHOULD NOT
advertise services with a scope attribute.
3.6. SL_GetServiceTypes
This returns an array of strings with all available service types.
Service Types with NAs will be returned as distinct Service Types,
ie. "blah" and "blah.xyz" are not the same.
This request may include a Scope. If it does not, it will only
return the Service Types of service advertisements made without a
Scope.
The request may also include a Naming Authority. If it does not,
only service types with the default NA will be returned ("IANA", or
no explicit NA.) If a specific NA is desired, this must be passed
in. If all Service Types are desired, irrespective of the NA, the
string "*" must be provided as the NA parameter.
3.7. SL_GetService
This interface takes a Query String. This string includes three
parts:
Guttman,Provan [Page 8]
Internet Draft An API for Service Location 24 March 1997
Service Type - (can be discovered using SL_GetServiceTypes)
Scope - (can be discovered using SL_GetScopes)
Query - (can be either a list or general query.
The attributes used in the query can be
discovered using SL_GetAttrs).
The Query portion of the parameter allows the caller to specify
exactly what service advertisement or advertisements are desired. See
section 6.3.3 for the string syntax of the Query.
This returns one or more service: URLs, their Lifetime in seconds and
address information ready to be used in networking calls.
3.8. SL_GetAttrs
If the URL supplied is a complete service: URL, the attribute
information returned will be for that particular service.
The service type string may include a NA suffix. The syntax for
including this is:
service-type-with-NA = srvtype-string "." NA-string
restricted-string = DIGIT / ALPHA / "+" / "-"
srvtype-string = 1*restricted-string
NA-string = 1*restricted-string
Attributes will only be returned for the service registered with the
Scope provided in the SL_GetAttrs call.
Finally, the result may be filtered with a Attribute Request Filter
string parameter. If this is not supplied, ALL attributes are
returned. If it is supplied, only those attributes on the list are.
An attribute tag with a '*' at the beginning, ending or both matches
all attributes whose attribute tag ends, starts or or contains the
substring, respectively.
"bob*" matches "bob" and "bobkat"
"*bob" matches "bob" and "some bob"
"*bob*" matches "bob", "bobkat", "some bob" and
"a bob example".
A Service Type string may be passed in as the URL parameter instead
of providing a complete service: URL. In this case, the results
which are returned are the attributes for ALL services of the
specified Service Type.
3.9. SL_Free
This API is only available for a C language interface. This function
frees all resources associated with the data passed in. The Result
pointer passed in will be modified to be NULL.
Guttman,Provan [Page 9]
Internet Draft An API for Service Location 24 March 1997
3.10 SL_Binary2Opaque
This API allows a buffer of arbitrary bytes to be encoded in a string
value appropriate for inclusion in a service advertisement.
4. API programming notes
4.1. Multithreading issues
Each SL_SrvHandle (C) or ServiceLocator Object (Java) will only allow
one concurrent access at a time. Interfaces are synchronous and will
block until they are complete. If a second thread attempts to use
the same SL_SrvHandle or ServiceLocator Object to perform a SLP API
function which has been labeled as 'synchronous', it will block until
the first thread completes its synchronous operation.
A multithreaded program may create multiple SL_SrvHandles or
ServiceLocator objects to make concurrent use of SLP interfaces.
4.2. Nonstandard Services Types are easy
It is trivial to register and discover services of nonstandard types.
Simply make up a Service Type string (by convention, nonstandard
service types begin with the string "x-").
4.3. Typical Client Scenarios
There are two typical use scenarios:
- canned query: Issue a SL_GetService. Try each service in turn
in the reply until one works.
- browse for a service: Issue SL_GetScopes. Issue SL_GetAttrs for
the desired Service Type using the selected Scope. Construct a
query string, then use SL_GetService. If the user wishes, call
SL_GetAttrs to get all (or some more) attributes for the service
returned by the SL_GetService.
4.4. Top level information
The SL_GetServiceTypes is used to implement network service browsers
and administrative tools. Normally a client application knows what
Service Type it will need.
Use the Service Template as a guide to designing client query and
service profile user interfaces. It can also be used for designing a
user interface for system administrators who will define the
attributes of a service. Service Templates are themselves a service
which can be discovered. See "The service: URL Scheme" [SRV].
4.5. Example applications of SLP
Guttman,Provan [Page 10]
Internet Draft An API for Service Location 24 March 1997
The most common use of SLP will simply be for clients to locate their
server by type and attribute. Many distributed applications require
discovery at configuration time. The SLP framework provides a
lightweight standard mechanism for doing this. Example domains which
might benefit are: Client-Server Database systems, network based
games, and distributed object systems.
Some more sophisticated examples are described below:
4.5.1. Coarse dynamic load balancing
One approach to load balancing simply distributes work on a rotating
basis among a set of servers. This rotation may be achieved using
redirection at various levels. This is a static approach: It has an
distribution algorithm which does not change depending on the actual
state of the servers.
A better approach could be to have the services provide feedback, so
as to allow dynamic load balancing. In this approach, the state of
the load of the services themselves determines the amount of work to
shift away or to the server.
To achieve this, services would have to be instrumented so as to
provide a "load metric." This attribute could be advertised using
SL_Register, updating the current service advertisement. The finest
granularity achievable given the timing of SLP would be on the order
of seconds. This is why I call the dynamic load balancing "coarse."
Clients seeking to dynamically discover a server with the lowest
"load metric" would first issue a SL_GetAttrs to obtain the range of
the attribute. Then, the SL_GetService function would be used, with
the query selecting the lowest load metric value. This would return
the service: URL to use.
4.5.2. Mobile user finds the nearest printer
A mobile user could use SL_GetAttrs to on the lpr service type,
requesting all "Location Description" and "Location Address"
attribute values be returned. The user is presented with this list
and selects the closest location. SL_GetServices is used to obtain
the service: URL which has this location attribute. The user may now
print and know where to find the result.
4.5.3. Providing highly available services
When a vital service needs to be brought down, users often suffer
down time. This requires network administrators to communicate with
their user community, defer nonessential maintenance and upgrades and
to schedule them at off hours.
Using Service Location, system administrators would need only start a
Guttman,Provan [Page 11]
Internet Draft An API for Service Location 24 March 1997
back up service and bring down the primary server. Client software
could simply rediscover the necessary service by type and
characteristic, reconnect and proceed.
This sounds harder than it would be in practice: The client software
would only need to be changed in one respect. The error path which
announced the client "lost contact with the server" would be changed.
The same code the client used for dynamically discovering the service
in the first place would be used again. Only if this rediscovery
fails need the software decry its sad disconnection.
5. API implementation issues
The primary goal of the API is to provide implementation independence
and SLP framework transparency. Some SLP transactions are
request/reply from one host to another, others require repeated
multicast and convergence, from one host to many. The SLP API
implementation must hide the details of this from the application
using it, so that only performance will vary given differences in the
SLP framework.
Results of requests should always be collated to remove duplicates.
This is especially important for the results of SL_GetAttrs and
SL_GetTypes when there are no DAs: The request will be multicast to
all SAs, and the results will no doubt include duplicate values.
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
hosts 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.
If the SA and DA are on the same host, it is possible that a request
might arrive which could be answered by both of them. It is never
wrong to reply with more information than the SLP semantics would
normally return.
The UA should evaluate the type of any given attribute by applying
the following algorithm. First, if the attribute's value is "TRUE" or
"FALSE", the attribute type is SL_BOOL_VAL. If the attribute's value
is a string representing a number between -2147483648 and 2147483647,
the type is SL_INT_VAL. If the attributes value is a string matching
the syntax '(' 1*DIGIT ':' radix-64-chars ')', it is SL_OPAQUE_VAL.
If none of these apply, then the attribute's type is SL_STR_VAL.
Guttman,Provan [Page 12]
Internet Draft An API for Service Location 24 March 1997
If an attribute has multiple values, the type of the values is
determined the following way: If ALL the values are consistent,
return the type of the values (ie. SL_INT_VAL for multiple integers.)
If the values are inconsistent, as for "(A=one, 1, true, (3:0000))",
the return type is SL_STR_VAL; all of A's values are considered
strings.
6. Language specific API specification and examples
The interfaces presented below are not equivalent, though they both
have the semantics described in sections 3, 4 and 5 above.
6.1 SLP API C bindings
6.1.1. Header file definitions
/*
* The SLP API definition.
*
* Published in: draft-ietf-svrloc-api-01.txt
* Erik Guttman
* Sun Microsystems, Inc.
* March, 1997
*
*/
/*-------------------------------------------------------------
* type declarations for service location
*/
#ifndef SLP_H
#define SLP_H
#ifdef __cplusplus
extern "C" {
#endif /* for C++ use of C interface */
typedef enum {
SL_LIFETIME_DEFAULT = 0xFFFF, /* use CONFIG_INTERVAL_1 */
SL_LIFETIME_NONE = 0 /* register indefinitely */
} SL_SpecialLifetime;
typedef enum {
SL_CHAR_ASCII = 3, SL_CHAR_LATIN1 = 4, SL_CHAR_UTF8 = 6
} SL_CharType;
typedef enum {
SL_TYPE_RESULT = 1, SL_ATTR_RESULT = 2, SL_SRV_RESULT = 3,
SL_SCOPE_RESULT = 4
} SL_ResType;
Guttman,Provan [Page 13]
Internet Draft An API for Service Location 24 March 1997
typedef enum {
SL_STR_VAL = 1, SL_INT_VAL = 2, SL_OPAQUE_VAL = 3,
SL_BOOL_VAL = 4
} SL_ValType;
/*-----------------------------------------------------------------
* SLP errors, can be received from a DA or SA.
*/
typedef enum {
SLP_OK = 0,
SLP_LANG_NOT_SUPPORTED = 0x01,
SLP_PROTOCOL_PARSE_ERR = 0x02,
SLP_INVALID_REGISTRATION = 0x03,
SLP_SCOPE_NOT_SUPPORTED = 0x04,
SLP_CHARSET_NOT_UNDERSTOOD = 0x05,
SLP_AUTHENTICATION_INVALID = 0x06,
/*-----------------------------------------------------------------
* Interface errors.
*/
SLP_NOT_SUPPORTED_YET = 0x10,
SLP_REQUEST_TIMED_OUT = 0x11,
SLP_COULD_NOT_INIT_NET_RESOURCES = 0x12,
SLP_COULD_NOT_ALLOCATE_MEMORY = 0x13,
SLP_PARAMETER_BAD = 0x14,
SLP_INTERNAL_NET_ERROR = 0x15,
SLP_INTERNAL_SYSTEM_ERROR = 0x16
} SL_Error ;
typedef enum {
SL_Srv_IgnoreCache = 0x01, /* Will ignore UA caches */
SL_Srv_DoNotResolve = 0x02, /* Will not resolve URL domain name */
/* to struct sockaddr_in */
SL_Srv_ForceMulticast = 0x04 /* Will not use DA, will multicast */
} SL_SrvFlags;
typedef struct servicetag {
char *s_pcURL;
struct sockaddr_in s_sin;
int s_iLifetime;
} SL_Service;
typedef struct opaquetag {
int op_iLen;
char *op_pcVal;
} SL_Opaque;
typedef union {
long intval;
int boolval;
Guttman,Provan [Page 14]
Internet Draft An API for Service Location 24 March 1997
SL_Opaque opaqueval;
char *pcStrVal;
} SL_Value;
typedef struct attrtag {
int a_iNumVals;
char *a_pcAttrTag;
SL_ValType a_slvaltype;
SL_Value *a_pslValue;
} SL_Attribute;
typedef union {
SL_Service i_sl_service;
SL_Attribute i_sl_attribute;
char *i_pcSrvtype;
char *i_pcScope;
} SL_ResInfo;
typedef struct resulttag {
SL_Error r_iErrorCode;
int r_iNumValues;
int r_iCharEncoding;
char *r_pcLang;
SL_ResType r_sl_restype;
SL_ResInfo *r_psl_Info;
} SL_Result;
typedef void* SL_SrvHandle;
/*------------------------------------------------------------
* Ease-of-use macros, to enable dereferencing of structures.
*
* res_srv_url returns the URL of the i'th service
* in the service result
* res_srv_sin returns the struct sockaddr_in of the
* i'th service in the service result
* res_srv_life returns the lifetime in seconds of the
* i'th service in the service result
* res_srvtype returns the string of the i'th service
* type in the service type result
* res_scope returns the scope string of the i'th
* scope result
* res_attr_numval returns the number of attr values for
* the i'th attr in the attr result.
* res_attr_tag returns the tag string for the i'th
* attr in the attr result
* res_attr_type returns the type for the i'th attr
* in the attr result
* res_attr_str returns the j'th string value of the
* i'th attr in the attr result
* res_attr_int returns the j'th int value of the i'th
Guttman,Provan [Page 15]
Internet Draft An API for Service Location 24 March 1997
* attr in the attr_result
* res_attr_bool returns the j'th boolean value of the
* i'th attr in the attr result
* res_attr_opaque returns the j'th opaque value of the
* i'th attr in the attr result
*/
#define res_srv_url(i) r_psl_Info[(i)].i_sl_service.s_pcURL
#define res_srv_sin(i) r_psl_Info[(i)].i_sl_service.s_sin
#define res_srv_life(i) r_psl_Info[(i)].i_sl_service.s_iLifetime
#define res_srvtype(i) r_psl_Info[(i)].i_pcSrvtype
#define res_scope(i) r_psl_Info[(i)].i_pcScope
#define res_attr_numval(i) r_psl_Info[(i)].i_sl_attribute.a_iNumVals
#define res_attr_tag(i) r_psl_Info[(i)].i_sl_attribute.a_pcAttrTag
#define res_attr_type(i) r_psl_Info[(i)].i_sl_attribute.a_slvaltype
#define res_attr_str(i,j) r_psl_Info[(i)].i_sl_attribute.a_pslValue[(j)].pcStrVal
#define res_attr_int(i,j) r_psl_Info[(i)].i_sl_attribute.a_pslValue[(j)].intval
#define res_attr_bool(i,j) r_psl_Info[(i)].i_sl_attribute.a_pslValue[(j)].boolval
#define res_attr_opaque(i,j) r_psl_Info[(i)].i_sl_attribute.a_pslValue[(j)].opaqueval
/*-------------------------------------------------------------------
* General interfaces for all clients
*
* The term "EXPORT" is included so as to make the interface portable
* to Win32. For Unix environments, etc. EXPORT is defined as nothing.
* For Win32, EXPORT is __declspec(dllimport) for the client library
* and __declspec(dllexport) for the library implementation.
*/
/*------------------------------------------------------------------*/
EXPORT SL_SrvHandle SL_Open(
SL_SrvHandle hSL_SrvHandle, /* State created by SL_Open */
const char *pcLangPref, /* Set to the ISO 639 code */
int iDialect, /* Set to 0, reserved */
int iMonoling, /* 1 = Monolingual, 0 = not */
int iMaxWait, /* # seconds max, 0 = default */
int iMultiple, /* 0 = return first result, */
/* 1 = return all results */
SL_CharType slchartype, /* Type for characters used. */
SL_Error *pErrValue); /* 0 unless an error occurred */
/*------------------------------------------------------------------*/
EXPORT void SL_Close(
SL_SrvHandle *pSL_SrvHandle); /* pSrvState from SL_Open */
/*------------------------------------------------------------------
* SA interfaces
*/
/*------------------------------------------------------------------*/
EXPORT SL_Error SL_Register(
Guttman,Provan [Page 16]
Internet Draft An API for Service Location 24 March 1997
SL_SrvHandle hSL_SrvHandle, /* State created by SL_Open */
const char *pcURL, /* Unique URL (of reg.) */
const char *pcLang, /* Language code of reg. */
int iDialect, /* Set to 0, reserved. */
SL_CharType slchartype, /* Character type of reg. */
const char *pcAttributes, /* Service Attribute list */
int iLifetime); /* 1..65534 = # of seconds */
/*------------------------------------------------------------------*/
EXPORT SL_Error SL_DeRegister(
SL_SrvHandle hSL_SrvHandle, /* State created by SL_Open */
const char *pcURL, /* URL (of service todereg.) */
const char *pcLang, /* Language code of dereg. */
int iDialect, /* Set to 0, reserved. */
SL_CharType slchartype, /* Character type of dereg. */
const char *pcAttrTags); /* Tags of attrs to dereg. */
/*------------------------------------------------------------------*/
/* SL_Binary2Opaque -
*
* This utility routine allows a service to convert a binary
* value into the opaque attribute value encoding used by
* Service Location. A binary buffer must be converted into
* a Radix-64 format so as to be transmitable in the string
* syntax.
*
* The SL_Opaque value is passed in for conversion. The
* caller must set both the fields: op_iLen (to the
* length of the buffer) and op_pcVal (to the buffer).
* The pcOpaqueBuffer is the buffer used by the library to
* store the results of the conversion from binary to
* opaque representation.
* The iLenOpaqueBuffer is the length of the buffer to store
* the string into. Note that this length must be ATLEAST
* (iLenBinaryBuffer*4)/3 + iLenOpaqueBuffer/10 + 5.
*
* If either buffer is not supplied or the lenght is insufficient
* the library will return a SLP_PARAMETER_BAD error.
*/
EXPORT SL_Error SL_Binary2Opaque(
const SL_Opaque *pslo, /* Opaque to convert */
char *pcOpaqueBuffer, /* User supplied data buffer */
int iLenOpaqueBuffer); /* Length of data buffer */
/*------------------------------------------------------------------
* UA interfaces
*/
/*------------------------------------------------------------------*/
Guttman,Provan [Page 17]
Internet Draft An API for Service Location 24 March 1997
/* SL_Result -
*
* Returns the list of scopes for DAs which have been discovered.
* If the UA or SA has been configured to use only a particular
* set of Scopes, (via DHCP or a static configuration file),
* these are the Scope strings which are returned.
*
* SL_Result is allocated by the library and must be freed using
* SL_FreeResult(SL_Result*).
*/
EXPORT SL_Result * SL_GetScopes(
SL_SrvHandle hSL_SrvHandle); /* State created by SL_Open */
/*------------------------------------------------------------------*/
EXPORT SL_Result * SL_GetSrvTypes(
SL_SrvHandle hSL_SrvHandle, /* State created by SL_Open */
const char *pcNamingAuth, /* NULL = default */
const char *pcScope); /* NULL = none */
/*------------------------------------------------------------------*/
EXPORT SL_Result * SL_GetAttrs(
SL_SrvHandle hSL_SrvHandle, /* State created by SL_Open */
const char *pcURL, /* Either full or partial */
const char *pcScope, /* Scope of attrs to get */
const char *pcAttrTags); /* Tags for 'selected' attrs */
/*------------------------------------------------------------------*/
EXPORT SL_Result * SL_GetService(
SL_SrvHandle hSL_SrvHandle, /* State created by SL_Open */
const char *pcRequest, /* Request string to supply */
int iFlags); /* 0 = none, otherwise '|' */
/* 'SL_Srv' flags, see above */
/*------------------------------------------------------------------*/
EXPORT void SL_FreeResult(
SL_SrvHandle hSL_SrvHandle, /* State created by SL_Open */
SL_Result **ppResult); /* SL_Result to be freed */
#ifdef __cplusplus
}
#endif /* for C++ use of C interface */
#endif /* End of the SLP API definition */
/*------------------------------------------------------------------*/
6.1.2. Interface clarification
The values #defined with SLP_ as their prefixes are the return values
of the interfaces. In the case of SL_Open, the return value is set
via an integer parameter supplied by the caller. In SL_Register and
Guttman,Provan [Page 18]
Internet Draft An API for Service Location 24 March 1997
SL_DeRegister the int is returned directly. In the case of all the
queries beginning with "SL_Get", the result code is in the Result
value returned, in the r_iErrorCode field of the structure. In the
case of an error, results MAY be returned on a best effort basis.
SL_Open
Pass NULL in as the SrvHandle parameter to create a new SrvHandle.
Pass an existing SrvHandle parameter to modify the default values
associated with it.
SL_Register
The pcLang and slchartype parameter must be set. See [SLP] for
a table of legitimate values for pcLang. iDialect MUST be set
to 0. See Section 6.3.4. for the syntax of pcAttributes.
A special service handle, SL_PERM_SRV_HANDLE, can be used to
register permanent services. Such services must be explicitly
deregistered: they would not be automatically deregistered when
the registering applications exits.
SL_DeRegister
The pcURL paramter must be set. Instead of deregistering the
service, one can deregister attributes. In this case the pcLang
and slchartype parameter must be set. iDialect MUST be set
to 0. See Section 6.3.5. for the syntax of pcAttrTags.
SL_PERM_SRV_HANDLE can be used to deregister permanent services.
SL_GetSrvTypes
The parameters may be NULL.
SL_GetAttrs
The pcURL parameter must be supplied. It can either be a
complete service: URL or merely a Service Type string. The
semantics of the call vary in this case.
The psScope parameter may be NULL.
The pcAttrTags parameter may be NULL. If it is not, it follows
the grammar in Section 6.3.6.
SL_GetService
The pcQuery must be supplied. It follows the grammar in Section
6.3.3.
Guttman,Provan [Page 19]
Internet Draft An API for Service Location 24 March 1997
SL_Free
The value of the Result will be freed, as well as the pointer
passed in.
SL_Binary2Opaque
The caller supplies a SL_Opaque to be converted and the buffer
into which the converted value will be copied.
6.1.3. Examples
Suppose web servers register themselves with Service Location.
The attributes they register are their Scope as well as an
index of all the 'home pages' available on the server. The
home pages are listed as
<relative URL> "::" <title> "::" <description>
The web server could do the following:
int err = SLP_OK;
SrvHandle sh = SL_Open(
NULL, /* NULL indicates: Create the SrvHandle */
"en", 0, /* Select English as default language */
1, /* Monolingual results for replies */
10, /* 10 seconds max blocking on calls */
1, /* Return all results */
CHAR_UTF8, /* All requests and replies in UTF8 */
&err); /* error value will be returned in err. */
if (err != SLP_OK) ; /* do something better here */
err = SL_Register(
sh, /* supply the SrvHandle */
"service:http://myhost.sun.com", /* supply the URL */
"en", 0, /* reg in English */
CHAR_ASCII, /* reg in UTF8 */
"(SCOPE=ENGINEERING)," /* declare attributes */
"(HOME PAGES="
"schedule/index.html::Schedule::"
"This site contains updated time lines 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"
"projects.)",
SL_LIFETIME_DEFAULT); /* use default lifetime */
if (err != SLP_OK) ; // do something better here
A web browser could use Service Location to find a particular web site
Guttman,Provan [Page 20]
Internet Draft An API for Service Location 24 March 1997
this way. Unlike web indexing search engines, SLP will keep information
up to date and it will be available within a few seconds after a web
server registers itself.
/*
* The client calls SL_Open, exactly as above.
*/
char *pcPageDescr = NULL;
Result *pr = SL_GetAttrs(
sh, /* The SrvHandle from SL_Open */
"http", /* The service type desired */
"ENGINEERING", /* The request's scope */
"HOME PAGES"); /* The attribute to return. */
if (pr->r_iErrorCode != SLP_OK) ; // do something better here
/*
* The client will examine the AttrResult and choose a HOME PAGE
*/
SL_Free(&pr); /* free previous result */
pr = SL_GetService(sh, "http/engineering/HOME PAGE ="
"specs/index.html::Specs galore::"
"Technical specifications for the F.L.O.R.B. and X872"
"projects./");
The service URL returned indicates the web server's address.
"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"
6.2. SLP API Java bindings
The ServiceLocator is created using a 'singleton' interface. This
allows the implementation to keep track of state pertains to all
instances of the class. The AttributeResult provides the same
information as the C interface, though in a different form. The
ServiceResult allows the creation of a Socket for immediate use of
the application protocol.
6.2.1. Class definitions
public class AttributeResult {
public static final int TYPE_STRING = 1;
public static final int TYPE_INT = 2;
public static final int TYPE_OPAQUE = 3;
public static final int TYPE_BOOL = 4;
public int getType();
Guttman,Provan [Page 21]
Internet Draft An API for Service Location 24 March 1997
public int getCharSet();
public String getLanguage();
public int getDialect();
public Vector vAttributes; // may have String, int, boolean or byte[]
};
public class ServiceResult {
public void setURL(String s) { sURL = new String(s); }
public void setLifetime(int i) { iLifetime = i; }
public void setAddress(InetAddress ia) { iaServiceAddress = ia; }
public void setPort(int i) { iPort = i; }
public String getURL() { return sURL; }
public int getLifetime() { return iLifetime; }
public InetAddress getAddress() { return iaServiceAddress; }
public int getPort() { return iPort; }
};
public class ServiceLocator {
// No Constructor
// Constants
public static final int CHAR_ASCII = 3;
public static final int CHAR_LATIN1 = 4;
public static final int CHAR_UTF8 = 6;
public static final int CHAR_UNICODE = 1000;
public static final int LIFETIME_NONE = 0;
public static final int LIFETIME_DEFAULT = -1;
// Class Methods
public static ServiceLocator getServiceLocator();
// Instance Methods
public String getLanguage(); // default to "en" (English)
public int getsDialect(); // set to 0
public boolean getMonolingual(); // default to true
public int getMaxWait(); // default to 10 (seconds)
public boolean getMultiple(); // default to true
public void setLanguage(String sLanguage);
public void setDialect(int iDialect); // do not use this
public void setMonolingual(boolean bMonolingual);
public void setMaxWait(int iMaxWait);
public void setMultiple(boolean iGetMultipleResults);
public synchronized void SL_Register(
String sURL,
String sLanguage,
int iDialect,
int iCharType,
Guttman,Provan [Page 22]
Internet Draft An API for Service Location 24 March 1997
String sAttributes[],
int iLifetime)
throws SLPException;
public synchronized void SL_DeRegister(
String sURL,
String sLanguage,
int iDialect,
int iCharType,
String sAttributes)
throws SLPException;
public synchronized String[] SL_GetScopes();
public synchronized String[] SL_GetServiceTypes(
String sNamingAuthority,
String sScope)
throws SLPException;
public synchronized SL_ServiceResult SL_GetService(
String sQuery)
throws SLPException;
public synchronized AttributeResult SL_GetAttrs(
String sURL,
String sScope,
String sAttributeTags)
throws SLPException;
public synchronized AttributeResult SL_GetAttrs(
String sServiceType,
String sScope,
String sAttributeTags)
throws SLPException;
public String SL_Binary2Opaque(
byte bBinary[]);
};
public class SLPException extends SLPException {
public SLPException();
public SLPException(String s);
};
// Exceptions caused by error conditions detected due to
// interaction with remote SLP entities (SAs and DAs)
public class SLPLanguageNotSupportedException extends SLPException {
public SLPLanguageNotSupportedException();
public SLPLanguageNotSupportedException(String s);
Guttman,Provan [Page 23]
Internet Draft An API for Service Location 24 March 1997
};
// Note: This error should never occur. It indicates a flawed
// underlying SLP implementation. Hence, it is an error
// not an exception.
public class SLPParseError extends SLPException {
public SLPParseException();
public SLPParseException(String s);
};
public class SLPInvalidRegistrationException extends SLPExcpetion {
public SLPInvalidRegistrationException();
public SLPInvalidRegistrationException(String s);
};
public class SLPScopeNotSupportedException extends SLPException {
public SLPScopeNotSupportedException();
public SLPScopeNotSupportedException(String s);
};
public class SLPCharsetNotUnderstoodException extends SLPException {
public SLPCharsetNotUnderstoodException();
public SLPCharsetNotUnderstoodException(String s);
};
public class SLPAuthenticationAbsentException extends SLPException {
public SLPAuthenticationAbsentException();
public SLPAuthenticationAbsentException(String s);
};
public class SLPAuthenticationFailedException extends SLPException {
public SLPAuthenticationFailedException();
public SLPAuthenticationFailedException(String s);
};
// Exceptions caused by error conditions arising through
// the program's use of the API or failure of the SLP
// implementation.
public class SLPNotSupportedYet extends SLPException {
public SLPNotSupportedYet();
public SLPNotSupportedYet(String s);
};
public class SLPTimeOutException extends SLPException {
public SLPTimeOutException();
public SLPTimeOutException(String s);
};
public class SLPInitNetException extends SLPException {
public SLPInitNetException();
Guttman,Provan [Page 24]
Internet Draft An API for Service Location 24 March 1997
public SLPInitNetException(String s);
};
// The 'message' SHOULD indicate which parameter was bad.
public class SLPParameterBadException extends SLPException {
public SLPParameterBadException();
public SLPParameterBadException(String s);
};
public class SLPInternalNetError extends SLPException {
public SLPInternalNetError();
public SLPInternalNetError(String s);
};
public class SLPInternalSystemError extends SLPException {
public SLPInternalSystemError();
public SLPInternalSystemError(String s);
};
6.2.2. Examples
A simplest application is: A server of type blah makes a service
advertisement:
try {
ServiceLocator sl = ServiceLocator.getServiceLocator();
sl.SL_Register("service:blah://myhost.sun.com", // service URL.
"en", 0, // Attributes is in English.
CHAR_ASCII, // Attribute uses ASCII.
"(SCOPE=ADMIN)", // The attribute.
12*60*60); // 12 hour lifetime
} catch (SLPException slpe) {} // do something better here
A blah client system can discover this with the following:
try {
ServiceLocator sl = ServiceLocator.getServiceLocator();
ServiceResult sr = sl.SL_GetService("blah/admin//");
} catch (SLPException) {} // do something better here
try { Socket s = new Socket(sr.iaServiceAddress, sr.iPort); }
catch (IOException) {} // do something better here
// ... now use s to do blah client-server stuff ...
Note that the scope matching is case insensitive. The query string
is omitted, so the request will return all blah services. The client
may then proceed to use the blah service, simply by creating a socket
from the information in the ServiceResult.
6.3. Syntax for string parameters
Guttman,Provan [Page 25]
Internet Draft An API for Service Location 24 March 1997
The definitions which follow are cumulative. The syntax is
specified using Augmented BNF [ABNF]. There are some rules which
specify explicitly what characters are NOT permitted.
For the syntax of the service: URL, see [SRV].
6.3.1. Character Escapes
If any string used in SLP includes a reserved character, it must be
escaped. For URLs, the escape mechanism is to replace the reserved
character with "%" HEX HEX where HEX is either a DIGIT or an ALPHA.
The encoding is the ASCII value of the reserved character. For
example:
service:http://www.zilch.net/some%20path%20with%20spaces
If any other string used in SLP (such as in a query string, an
attribute list used in registration or an attribute reply, and so
on,) the character escape mechanism used is to replace the reserved
character with "&#" 1*DIGIT ";". Here DIGIT is to be interpreted as
a decimal representation of the character to be escaped, given the
character set of the string encoding. For example:
(attr=value with a comma, and an asterix *)
6.3.2. string matching
Attribute tags and values may be used by some protocols for directory
look-up. In this case, the following rules should be applied for
string matching of attribute strings.
String matching MUST be done after character escape encoding has been
removed, white space has been trimmed. In addition, string matching
SHOULD be case insensitive.
6.3.3. Query Syntax
This is used in SL_GetService (See Section 3.7.)
A Query may take two forms.
white = SPACE / TAB / CR / LF
query = listquery / ; conjunction query
generalquery / ; complex query
*white ; ie. the query matches everything
These are defined in the next sections. The list-query is a very
simple form. The general-query allows arbitrarily complex logical
combinations of conditions.
Guttman,Provan [Page 26]
Internet Draft An API for Service Location 24 March 1997
Common syntax to both kinds of queries follows:
predicate = srvtype [ "." na ] "/" scope "/" query "/"
schemechar = DIGIT / ALPHA / "+" / "-"
srvtype = 1*schemechar
na = 1*schemechar
; omit na when it is "IANA", the default
scope = ; Any string with the following restrictions:
; "/", ",", and ":" are not allowed in this
; string. "LOCAL" and "REMOTE" scope strings are
; reserved.
safe-char = ; Any character with the following restrictions:
; "(", ")", ",", "=", "!", ">", "<", "/", "*"
; are not allowed. They must be escaped (see
; Section 6.3.1.).
attr-tag = 1*safe-char
safer-char = ; As safe-char but SPACE is also not allowed.
keyword = 1*safer-char
query-item = keyword / attr-tag comp-op value
comp-op = "!=" / "==" / "<" / "<=" / ">" / ">="
value = string / integer / boolean / opaque / partial-str
string = 1*safe-char
integer = [-] 1*DIGIT
; The integer MUST fall within the range of
; values a 32 bit integer may take, ie.
; "-2147483648" to "2147483647".
boolean = "TRUE" / "FALSE"
; These values are the only exception to the
; Internationalization rules in Section 8.0.
; Independent of the translation of the
; attributes, the boolean values remain the
; indicated strings.
rad64-char = ALPHA / DIGIT / "+" / "-" / white-sp
opaque = 1*DIGIT ":" 4*rad64-char
; The digits define the original length of the
Guttman,Provan [Page 27]
Internet Draft An API for Service Location 24 March 1997
; opaque value. The restricted character string
; is the radix-64 encoding of the opaque value.
; See [RFC 1521], Section 5.2.
; NOTE: White space is ignored in decoding
; radix-64 values.
partial-str = ["*"] string ["*"]
; If preceded by a "*", it matches all string
; values ending with the string. If followed
; by a "*", it matches all string values which
; begin with the string. If both followed and
; preceded by a "*", it matches all string
; values which contain the string. Refer to
; section 3.8 for examples.
6.3.3.1. List Query Syntax
list-query = 1#query-item
6.3.3.2. General Query Syntax
general-query = "(" "&" general-query query-item-list ")" /
"(" "|" general-query query-item-list ")" /
"(" query-item ")"
query-item-list = general-query /
general-query query-item-list
6.3.3.3. White Space
A string is considered to be a token in the case of a tag or
<string> value. In this case, the string is 'trimmed'. White
space interior to a string token is left alone, while white
space between the tokens is removed. For example:
" some name = some value , another example "
would be trimmed to
"some name" "=" "some value" and "another example".
6.3.4. Attribute Registration List
This is used in SL_Register (See Section 3.3.)
attr-reg-list = 1#attr-reg
attr-reg = keyword / "(" attr-tag = 1#value ")
6.3.5. Attribute Deregistration List
Guttman,Provan [Page 28]
Internet Draft An API for Service Location 24 March 1997
This is used in SL_DeRegister (See Section 3.4.)
attr-dereg-list = 1#attr-dereg
attr-dereg = keyword / attr-tag
6.3.6. Attribute Selection List Syntax
This is used in SL_GetAttrs (See Section 3.8.)
attr_select_list = 1#attr-select
attr_select = keyword / attr-tag / partial-tag
partial_tag = 1*safe-char "*"
6.4. Configuration File Format
The following configuration file format is included so that static
configuration files for one implementation of the SLP framework will
be useful for other implementations.
config-file = [discovery-opts] [policy] [timing]
discovery-opts = [da-discovery] [scope-discovery]
da-discovery = "DA-DISCOVERY" "=" *disc-opts CRLF
disc-opts = ["NO-DYNAMIC"] /
["DHCP"] /
["STATIC"] /
["STRICT"]
scope-discovery= "SCOPE-DISCOVERY" "=" *disc-opts CRLF
If da-discovery includes the "STATIC" option, a static
list of DAs must be provided. This list has the following
format:
da-list = "DA" "=" da-def *(break da-def) CRLF
da-def = fqdn /
dotted-decimal-ipv4 /
dotted-decimal-ipv6
break = CRLF 1*SPACE
; Note - terms not beginning on the first
; column of the configuration file are
; considered continuations of a pervious
; configuration parameter's definition.
If scope-discovery includes the "STATIC" option a
static list of Scopes must be provided. This list has
the following format:
Guttman,Provan [Page 29]
Internet Draft An API for Service Location 24 March 1997
scope-list = "SCOPE" "=" scope-def *(break scope-def) CRLF
scope-chars = ALPHA / DIGIT / "+" / "-"
scope-def = 1*scope-chars
The meaning of the disc-opts are as follows:
NO-DYNAMIC
Do not use multicast or broadcast for discovery. Use
of these is the default for the Service Location Protocol
so this must be explicitly turned off with this configuration
option.
DHCP
Use DHCP to acquire a list of DAs or a list of Scopes to
use.
STATIC
Use the static list of DAs or Scopes which is provided.
The order of the DHCP and STATIC options is relevant, if
both options are provided. Whichever is first will take
precedence over the other. If NO-DYNAMIC is *not* present
dynamic information will always take the last place in
lists of Scopes and DAs.
STRICT
In the context of scope-discovery, strict means that no
registration or request may be issued unless it uses a
scope.
In the context of da-discovery, this option indicates
that passive DA discovery is disabled.
policy = *policy-options
policy-options = ["USE-BROADCAST" CRLF] /
["MULTICAST-RADIUS" "=" radius] /
["MTU" "=" size]
radius = 1..32
; That is, an integer from 1 to 32
size = *DIGIT
; This is the maximum transmission unit for
; the link layer used. The recommended default
; for SLP is 1400.
Guttman,Provan [Page 30]
Internet Draft An API for Service Location 24 March 1997
timing = *timing-opts
timing-opts = ["TIME-0-CACHE-REPLIES" "=" seconds] /
["TIME-1-REG-LIFETIME" "=" seconds] /
["TIME-2-RETRY-MCAST-Q" "=" times] /
["TIME-3-WAIT-MCAST-Q" "=" seconds] /
["TIME-4-WAIT-REGISTER" "=" seconds] /
["TIME-5-RETRY-DA-DISC" "=" times] /
["TIME-6-QUIT-DA-WAIT" "=" seconds] /
["TIME-7-QUIT-DA-DISC" "=" seconds] /
["TIME-8-QUIT-SA-Q" "=" seconds] /
["TIME-9-DA-HEARTBEAT" "=" seconds] /
["TIME-10-WAIT-REG-DA-PASSIVE" "=" seconds] /
["TIME-11-WAIT-REG-DA-ACTIVE" "=" seconds] /
["TIME-12-QUIT-IDLE-CONNECTS" "=" seconds]
; Please refer to [SLP] for the definitions of
; these configuration options.
7.0. Interpretation of SLP error values
SLP will only return an error code when an operation fails
completely. If the request is partially satisfied -- at least one
service is discovered, for example -- then SLP_OK is returned.
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. SLP 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. On the other hand, it can also be
caused by damage to the packet in the network.
SLP_INVALID_REGISTRATION
SLP may return this error if an attempt to register a service was
rejected by all DAs because of a malformed URL or attributes. SLP
Guttman,Provan [Page 31]
Internet Draft An API for Service Location 24 March 1997
will not return the error if at least one DA accepted the
registration.
SLP_SCOPE_NOT_SUPPORTED
SLP may return this error code if the indicated scope is not known
to the system. For example, if SLP 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
SLP 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_ABSENT
If the SLP framework supports authentication, this error will arise
when a remote DA fails to accept a registration. This will occur if
a SA attempts to register a service into a protected scope without
including an authenticator.
SLP_AUTHENTICATION_INVALID
If the SLP framework supports authentication, this error will arise
when a remote DA fails to accept a registration or deregistration
due to an invalid authenticator. 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
When a particular feature is used which is not implemented in the
API, this error is returned. This error SHOULD not occur.
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.
SLP_COULD_NOT_ALLOCATE_MEMORY
Guttman,Provan [Page 32]
Internet Draft An API for Service Location 24 March 1997
If the API or SLP implementation 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 SLP implementation causes this error to be
returned. This occurs when a system call or library fails. The
operation could not recover.
8. Security Considerations
SLP will make use of an existing host based authentication framework
once it becomes available as an Internet Standard. [RFC1825]
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" [SSH] or
application level: "Generic Security Service Application Program
Interface" [GSSAPI],) 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.
9. Internationalization Considerations
Guttman,Provan [Page 33]
Internet Draft An API for Service Location 24 March 1997
The service: URL itself must be encoded using the rules set forth in
[RFC1738]. The character set encoding is limited to specific ranges
within the US-ASCII character set [ASCII].
The attribute information associated with the service: URL may be
expressed in any character set, and in any language.
9.1. Character Set identification and use
The way of identifying the character set used is the IANA Character
Set registry MIB Enum value. [CHAR-REG]
It can be assumed that US-ASCII [ASCII] 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 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.
9.2. Language identification and translation
The language used in attribute string should be identified using a
Language tag as defined by [ISO-639]. The dialect parameter to all
interfaces should be ignored. It is included for forward
compatibility, as it is likely that the treatment of languages in
the interface will change.
A program registering a service should use the strings provided in
the Service Type template which defines the range of standard
values. If this document provides translations to other languages,
the service advertisement should be made in each.
If however no translation exists, or there is no standardized
Service Type template, translation may still be provided on a "best
effort" basis.
A service advertisement is made in multiple languages, one after the
other. The same information is registered using SL_Register, though
the Language tag differs and the strings are translated. Many
attribute strings are 'literal' and will not be translated. See
[SRV] for details.
10. Bibliography
[ABNF] D. Crocker, "Augmented BNF for Syntax Specifications:
Guttman,Provan [Page 34]
Internet Draft An API for Service Location 24 March 1997
ABNF", Work in progress, November 1996.
[ASCII] "Coded Character Set -- 7-bit American Standard code
for Information Interchange", ANSI X3.4-1986.
[CHAR-REG] IANA Character Set registry, <URL:http://www.isi.edu
/in-notes/iana/assignments/character-sets>.
[GSSAPI] J. Linn, "Generic Security Service Application Program
Interface", RFC 1508, September 1993. Also:
J. Linn, "Generic Security Service Application Program
Interface, Version 2", A work in progress,
November 1996.
[RFC1825] R. Atkinson, "Security Architecture for the Internet
Protocol", RFC 1825, July 1995.
[SSH] A. Freier, P. Karlton, P. Kocher, "The SSL Protocol,
Version 3.0", A work in progress, November 1996.
[SLP] J. Veizades, E. Guttman, C. Perkins & S. Kaplan,
Service Location Protocol", Work in progress,
March 1997.
[SRV] E. Guttman, "The service: URL Scheme", Work in
progress, November 1996.
[ISO-639] This standard is provided as Appendix A of [SLP].
Guttman,Provan [Page 35]
Internet Draft An API for Service Location 24 March 1997
11. Authors' Addresses
Erik Guttman
Sun Microsystems, Inc.
Gaisbergstr. 6
D-69115 Heidelberg
Germany
Phone: +1 49 6221 601649
email: Erik.Guttman@eng.sun.com
Don Provan
Novell, Inc.
2180 Fortune Drive
San Jose, CA 95131
USA
Phone: +1 408 577 8440
email: donp@novell.com
This memo expires on September 24, 1997
Guttman,Provan [Page 36]
