Subject: draft-kempf-2614bis-00.txt

From: James Kempf <[email-masked]>
Date: Fri, 22 Dec 2000 11:29:21 -0800 (PST)

Please retract the previous submission for this. Attached is draft-kempf-2614bis-00.txt,
an individual contribution of interest to the SrvLoc working group.

		jak

INTERNET DRAFT                                                James Kempf
Category: Informational                              Sun Microsystems, Inc.
Title: draft-kempf-2614bis-00.txt                             Erik Guttman
Date: December 2000                                  Sun Microsystems, Inc.

                Modifications to the SLP API (RFC 2614)

                          Status of this Memo

   This document is an individual contribution for consideration by the
   Service Location Working Group of the Internet Engineering Task
   Force.

   Distribution of this memo is unlimited.

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.  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."

   The list of current Internet-Drafts can be accessed at:

      http://www.ietf.org/ietf/1id-abstracts.txt

   The list of Internet-Draft Shadow Directories can be accessed at:

      http://www.ietf.org/shadow.html.

   Copyright   (C) The Internet Society 2000.  All Rights Reserved.

Kempf, Guttman             expires June 2001                    [Page 1]

INTERNET DRAFT                                             December 2000

Abstract

   The SLP API been implemented on a few different platforms. Based on
   the experience of implementors, some minor changes are necessary to
   improve usability. This draft documents those changes.

Table of Contents

   1.0 Introduction
   2.0 Proposed Changes
   3.0 References
   4.0 Acknowledgements
   5.0 Authors' Addresses
   6.0 Full Copyright Statement

1.0 Introduction

   The SLP API has been implemented on a few different platforms, and in
   the process of implementation, a few problem areas have been
   discovered. These are not major changes in function but rather simple
   changes that improve usability. The following section documents
   changes to RFC 2614 [1].

2.0 Proposed Changes

2.1 Number of SLPAttrCallback() Calls.

   If a client calls SLPGetAttrs() to obtain the attributes of a URL,
   the current specification leaves it ambiguous how many times the
   callback will be called.

   In the case of a SrvRqst by URL, only one reply message is necessary;
   therefore, SLPAttrCallback() will be called only once with an
   attribute list (or none if no list was returned). As with all
   callbacks, however, a second call will occur with the errorCode
   parameter set to SLP_LAST_CALL, indicating that the callback is
   finished.

2.2 SLPFreeURL() Should Be SLPFree()

   The description of SLPParseURL() mentions that the memory should be
   freed with SLPFreeURL(). The function should be SLPFree().

2.3 SLPGetProperty() Could Cause Memory Leaks

   The current definition of SLPGetProperty() requires the client to not
   deallocate the returned memory. The assumption here is that the
   library holds a pointer to constant memory. However, if the client

Kempf, Guttman             expires June 2001                    [Page 2]

INTERNET DRAFT                                             December 2000

   modifies the property with SLPSetProperty() subsequent to obtaining a
   pointer, the memory cannot be freed by the library either, because
   the client is potentially holding a pointer. This could cause memory
   leaks.

   As a result, the SLPGetProperty() API changes to:

      SLPError SLPGetProperty(const char* propertyName,
                              char** propertyValue);

      Upon return, the propertyValue parameter is set to a pointer to
      the property value string, or NULL if the propertyName does not
      name a valid SLP property. The application is responsible for
      calling SLPFree() on the property to free the memory.

      Error codes that are returned:  SLP_OK, SLP_MEMORY_ALLOC_FAILED,
      SLP_NOT_IMPLEMENTED, or SLP_PARAMETER_BAD. The latter is returned
      if the propertyName parameter does not name a valid SLP property.

2.4. Addition of SLPParseAttrs() Function

   Parsing of returned attribute list is a function that every API
   library client requires and therefore the library should provide some
   lightweight support for attribute list parsing. The function
   described in the following sections is proposed.

2.4.1. Synopsis

      SLPError SLPParseAttrs(const char* pcAttrList,
                             const char *pcAttrId,
                             char** ppcAttrVal);

2.4.1. Description

   Parses an attribute list to obtain the attribute value of a specified
   attribute ID.  The attribute value string returned in ppcAttrVal must
   be freed with SLPFree().  SLP_PARSE_ERROR is returned if a value for
   pcAttrId can not be found.

2.4.2. Parameters

      pcAttrList

         A character buffer containing a comma separated, null
         terminated list of attribute id/value assignments, in SLP wire
         format; i.e.  "(attr-id=attr-value-list),..." [2].

      pcAttrId

Kempf, Guttman             expires June 2001                    [Page 3]

INTERNET DRAFT                                             December 2000

         The string indicating which attribute value to return, which
         must not be NULL or the empty string ("").

      ppcAttrVal

         A pointer to a pointer to the buffer to receive attribute
         attribute value, returned by the function.  The returned memory
         should be freed by a call to SLPFree() when no longer needed.

2.4.3. Returns

   If no error occurs, the return value is SLP_OK. Otherwise, the
   appropriate error code is returned. If this function is not
   implemented, the library should return SLP_NOT_IMPLEMENTED.  If a
   parse error occurs, the library should return SLP_PARSE_ERROR.

2.5 URL Format

   RFC 2614 is not explicit about the need for supplying strings having
   URL format for all functions that accept service URLs.  Text needs to
   be added to the appropriate API function definitions making this
   explicit. The format is not restricted to the service:  URL format,
   however the strings must be properly formatted URLs.  Otherwise, the
   function must return SLP_PARSE_ERROR.

2.6 Configured v.s. Discovered Scope List

   Currently, the API has no way for a UA client to distinguish between
   configured v.s. discovered scopes. The SLPFindScopes() function
   returns all scopes, both configured and discovered. The
   net.slp.useScopes property is not well defined. The current text is
   ambiguous about whether it contains configured and discovered, or
   just configured; and if just configured, then whether DCHP configured
   scopes are included as well.

   The text in Section 2.1.2 defining net.slp.useScopes should be
   rewritten to clarify that net.slp.useScopes contains a list of all
   configured scopes, both static and DHCP. The text in Section 4.6.2
   and Section 5.5 should be rewritten to clarify that SLPFindScopes()
   and ServiceLocationManger.findScopes() return both configured and
   discovered scopes.

2.7 Sensible Scope Defaulting Mechanism Required

   The current draft requires a programmer to call SLPFindScopes() or
   ServiceLocationManager.findScopes() to discover scopes, or retrieve
   the net.slp.useScopes property. If the programmer simply wants to

Kempf, Guttman             expires June 2001                    [Page 4]

INTERNET DRAFT                                             December 2000

   default to the current set of administrator-configured scopes, there
   is no need for the additional function call.

   All functions and methods that take a scope string (C) or vector of
   scope names (Java) should accept the empty string ("") or empty
   vector as meaning "take the default configured scopes from
   net.slp.useScopes".

3.0 References

   [1] Kempf, J. and Guttman, E., "An API for Service Location", RFC
   2614, April, 1999.

   [2] Guttman, E., Perkins, C., Veizades, J., and Day, M., "Service
   Location Protocol, Version 2", RFC 2608, January, 1999.

4.0 Acknowledgements

   Matthew Peterson, of the OpenSLP project at Caldera Systems, provided
   the definition for SLPParseAttrs() and suggested cleaning up URL
   format and scope handling.

5.0 Authors' Addresses

     James Kempf
     Sun Labs California
     Sun Microsystems, Inc.
     901 San Antonio Rd., UMPK15-214
     Palo Alto, CA, 94303
     USA

     Phone: +1 650 786 5890
       Fax: +1 650 786 6445
     EMail: [email-masked]

     Erik Guttman
     Sun Microsystems, Inc.
     Eichhoelzelstr. 7
     74915 Waibstadt
     Germany

     Phone: +49 172 865 5497
       Fax: +49 7263 911 701
     Email: [email-masked]

6.0  Full Copyright Statement

Kempf, Guttman             expires June 2001                    [Page 5]

INTERNET DRAFT                                             December 2000

   Copyright (C) The Internet Society (2000).  All Rights Reserved.

   This document and translations of it may be copied  and  furnished
   to others,  and  derivative works that comment on or otherwise
   explain it or assist in its implementation may be prepared, copied,
   published and distributed,  in  whole  or  in part, without
   restriction of any kind, provided that the  above  copyright  notice
   and  this  paragraph  are included on all such copies and derivative
   works.  However, this docu- ment itself may not be modified in any
   way, such as  by  removing  the copyright notice or references to the
   Internet Society or other Inter- net organizations, except as needed
   for  the  purpose  of  developing Internet standards in which case
   the procedures for copyrights defined in the Internet Standards
   process must be followed, or as required  to translate it into
   languages other than   English.  The limited permis- sions granted
   above are perpetual and  will  not  be  revoked  by  the Internet
   Society or its successors or assigns.  This document and the
   information contained herein is provided on an "AS IS" basis  and
   THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE
   DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
   LIMITED TO ANY  WAR- RANTY  THAT  THE  USE  OF THE INFORMATION HEREIN
   WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS  FOR  A PARTICULAR PURPOSE."

Kempf, Guttman             expires June 2001                    [Page 6]