Network Services Location Tech
Volume Number: 14
Issue Number: 7
Column Tag: Emerging Technologies
Network Services Location Technology
by by the Apple Network Services Location Project Team
Edited by Peter N Lewis
How the NSL Technology Can Benefit Your Application
When Apple introduced the Chooser and AppleTalk, they allowed users unprecedented
ease-of-use in browsing for network services such as printers and file servers. With
the introduction of the Network Services Location (NSL) Technology, Apple is bringing
that same ease-of-use to the Internet. With NSL users have the ability to browse
through Internet services such as FTP and HTTP via TCP/IP in the same way they have
traditionally browsed for AppleTalk services using the Chooser. By adopting this
technology, applications can provide a more intuitive and convenient method for users
to access network services.
The NSL Technology is composed of a Manager and a set of plug-ins that gather data via
particular network protocols (such as DNS). The NSL Manager provides a single API
across any number of resource discovery protocols, and by developing additional
plug-ins, new methods for resource discovery can be added with no additional work on
the part of the application developer. In this article we will present the NSL
technology and show you, the developer, how to incorporate it into your next project.
What is NSL?
The Network Services Location Manager provides a protocol-independent way for
applications to discover available network services with minimal network traffic. The
NSL Manager provides:
• AppleTalk-like ease-of-use for the dynamic discovery of traditional and
non-traditional network services.
• Support for accepted and proposed industry standards, including Domain
Name Service (DNS) and Service Location Protocol (SLP). SLP is an emerging
standard (see RFC 2165) for registering and finding Internet services
dynamically.
• A flexible, expandable architecture that can be easily leveraged by client
and server applications.
A variety of applications can benefit from NSL technology. Calls to the NSL Manager
can make these applications more intuitive and easier to use. For example:
• Instead of requiring the user to type a URL to locate a web server, a
browser application that calls the NSL Manager could have an "Open Location
command that polls a network for HTTP servers and returns a list of URLs in
the browser window from which a particular URL can be selected.
• Collaboration software, such as a video conferencing server could register
itself as an available service on the corporate Intranet. The users of client
video conferencing software could then search the Intranet for available
conferences and join a particular conference without having to remember a
cryptic URL or IP address.
Using NSL
The NSL Manager acts as an intermediary between the providers of network services
and applications that want information about those services. Service applications
register themselves with the NSL Manager and which then acts through NSL plug-ins
to perform the actual searches. The NSL Manager can pass requests from applications
to any plug-in that implements the NSL Manager API.
An NSL plug-in is an extension that makes itself available to the NSL Manager when
the NSL Manager is initialized, but resides in memory only when it is responding to an
application's lookup request. The Extensions Manager can be used to enable and disable
individual NSL plug-ins. When the NSL Manager is initialized, each NSL plug-in
provides the following information to the NSL Manager:
• The types of services the plug-in can search for, such as HTTP and FTP.
• The protocol the plug-in uses to conduct searches, such as DNS.
The NSL Manager will be available on all PowerPC-based computers that run the Mac
OS release code-named Allegro or later. The first release will be accompanied by two
NSL plug-ins: DNS and SLP. Additional NSL plug-ins may also become available from
Apple Computer or third-party developers.
Figure 1 illustrates the relationship between applications, the NSL Manager, and
NSL plug-ins.
Figure 1. The relationship between the NSL Manager, NSL plug-ins, and
Applications.
To search for network services, an application opens a session with the NSL Manager
using NSLOpenNavigationAPI:
status = NSLOpenNavigationAPI( &gOurClientRef );
Then it must prepare three data values that are used as parameters to the
NSLStartServicesLookup function:
• A request parameter block that describes the services you want to look
for.
• A lookup request that describes how you want results to be returned to
you.
• A neighborhood that describes the virtual "geographic" scope of the
search.
Creating the Request Parameter Block
To create a request parameter block, your application first makes a service list that
specifies the services to be searched for using NSLMakeNewServicesList and then pass
the service list and any attributes to NSLMakeRequestPB. For example, to search for
HTTP and FTP services, you would do something like this:
serviceList = NSLMakeNewServicesList( "http,ftp" );
iErr.theErr = NSLMakeRequestPB( serviceList, "",&newDataPtr);
In the call to NSLMakeRequestPB, your application can use the attribute parameter to
specify a string that is to be used to narrow the scope of the search. For example, if the
attribute parameter is "Web Sharing," the search results will include only those
Personal Web Sharing HTTP services that have registered with "Web Sharing" as an
attribute.
Creating the Lookup Request
To create a synchronous lookup request, your application calls NSLPrepareRequest
like this:
iErr = NSLPrepareRequest( NULL, NULL, gOurClientRef, &ourRequestRef,
buffer, bufLen, &ourAsyncInfo );
To create an asynchronous lookup request, your application calls NSLPrepareRequest
like this:
iErr = NSLPrepareRequest( notifierPtr, NULL, gOurClientRef,
&ourRequestRef,buffer, bufLen, &ourAsyncInfo );
When you call NSLPrepareRequest, you can specify NULL as the value for the notifier
parameter (the first parameter in the first call above), if you want to wait for search
results to be returned (synchronous mode). If instead, you want the NSL Manager to
call your notification routine when search results are ready to be returned
(asynchronous mode), specify a pointer to your notification routine. In the second call
above notifierPtr is a procedure pointer to the client's asynchronous notifier.
The other parameters to the NSLPrepareRequest function are:
• contextPtr, which you can use to specify contextual information about
this lookup.
• theClient, which is a value that your application received when it opened a
with the NSL Manager.
• ref, which on output is a pointer to the search request that
NSLPrepareRequest will create.
• bufPtr, which is a pointer to the buffer in which search results are to be
placed.
• bufLen, which is the length of bufPtr.
• infoPtr, which is a structure that contains values, such as a maximum
search time and the interval at which NSL Manager is to return search
results, that control how the search will be conducted. Your application can
change the default values before it starts the search.
Creating the Neighborhood
To define the virtual "geographic" boundary of the search, your application calls
NSLMakeNewNeighborhood. You can explicitly specify which a neighborhood, for
example apple.com. In the following example, the application creates a neighborhood
whose boundary is apple.com.
neighborhood = NSLMakeNewNeighborhood("apple.com", NULL );
Or, you can use the default neighborhood:
neighborhood = NSLMakeNewNeighborhood( "", NULL );
Starting the Lookup
Once your application has created the request parameter block, the lookup request, and
the neighborhood, it calls NSLStartServicesLookup to start the search:
iErr = NSLStartServicesLookup( ourRequestRef, neighborhood,
newDataPtr, ourAsyncInfo );
The parameters to the NSLStartServices function are:
• ref, which is the search request created when your application called
NSLPrepareRequest.
• neighborhood, which is the neighborhood value created earlier by calling
NSLMakeNewNeighborhood.
• requestData, which is the request parameter block created by calling
NSLMakeRequestPB.
• asyncInfo, which is the structure that contains values that control the
way the NSL Manager returns search results, obtained by previously calling
NSLPrepareRequest.
Continuing the Lookup
If the NSLStartServicesLookup was called synchronously, NSLStartServicesLookup
returns after having placed the first lookup results in the results buffer field of
asyncInfo. If NSLStartServicesLookup was called asynchronously, the NSL Manager
places the first lookup results in the results buffer and calls your application's
notification routine. Your application copies the results and calls NSLContinueLookup,
which continues the lookup and returns more lookup results in the results buffer.
Your application continues to call NSLContinueLookup until all of the results have been
returned.
Conclusion
This article has provided a brief overview of NSL. For more detailed information on
the NSL technology, API and sample User Interface recommendations, please refer to
the Network Services Location Manager Developer's Kit Documentation located in the
July issue of the Mac OS SDK CD distributed by Apple Computer, Inc.
______________________________
The authors of this article are members of the Network Services Location Project
Team at Apple Computer, Inc.