Carbon


NSLStartServicesLookup

Header: NSL.h Carbon status: Supported

Looks for services.

NSLError NSLStartServicesLookup (
    NSLRequestRef ref, 
    NSLNeighborhood neighborhood, 
    NSLTypedDataPtr requestData, 
    NSLClientAsyncInfo *asyncInfo
);
Parameter descriptions
ref

On input, an NSLRequestRef created by previously calling NSLPrepareRequest.

neighborhood

On input, an NSLNeighborhood value created by previously calling NSLMakeNewNeighborhood.

requestData

On input, a parameter block that describes the search parameters. To format requestData properly, call NSLMakeServicesRequestPB.

asyncInfo

On input, a pointer to a NSLClientAsyncInfo structure obtained by calling NSLPrepareRequest.

function result

If the value of NSLError.theErr is noErr, NSLStartServicesLookup returned successfully. Other possible values are kNSLNotInitialized, kNSLSearchAlreadyInProgress, kNSLNoPluginsForSearch, kNSLNullNeighborhoodPtr, and kNSLBufferTooSmallForData.

DISCUSSION

The NSLStartServicesLookup function starts a service lookup.

For any NSLRequestRef, only one neighborhood or service lookup can be ongoing at any one time.

When the NSL Manager calls your application’s notification routine, it should check the value of asyncInfo.searchState, which contains one of the following values:

kNSLSearchStateBufferFull = 1,

kNSLSearchStateOnGoing = 2,

kNSLSearchStateComplete = 3,

kNSLSearchStateStalled = 4

If the value of asyncInfo.searchState is kNSLSearchStatusBufferFull, your application should process the data returned in asyncInfo.resultBuffer and return, thereby continuing the lookup.

If the value of asyncInfo.searchState is kNSLSearchStateOnGoing, the value of asyncInfo.alertInterval or asyncInfo.alertThreshold has been reached. Your application should process the data returned in asyncInfo.resultBuffer and return, thereby continuing the lookup.

If the value of asyncInfo.searchState is kNSLSearchStateComplete, the lookup is complete. Your application should process the data returned in asyncInfo.resultBuffer.

If the value of asyncInfo.searchState is kNSLSearchStateStalled, the value of asyncInfo.alertInterval or asyncInfo.maxSearchTime has been reached, but there is no data in the result buffer. One or more plug-ins for this lookup is waiting to receive data from a server but has not yet timed out. If the value of asyncInfo.searchState is noErr, your application’s notification routine should ignore the notification and return immediately, thereby resuming the lookup.

If NSLStartServicesLookup returns kNSLBufferTooSmallForData, the value of asyncInfo.maxBuffserSize is too small to hold an item that would otherwise have been returned. Your notification routine can cancel and restart the lookup, or it can ignore the error and return, thereby resuming the lookup even though some data will be lost.

If more than one plug-in participates in a lookup, the result buffer may contain valid data even though NSLStartServicesLookup returns an error code from one of the plug-ins. If the value of asyncInfo.searchState is kNSLSearchStateBufferFull, your application should process the data in the result buffer.

To cancel an ongoing lookup, call NSLCancelRequest.

NSLGetNextUrl for information about processing the data in the result buffer. NSLDeleteRequest for information about deleting a lookup request that is no longer needed.


© 2000 Apple Computer, Inc. (Last Updated 7/13/2000)