![]() |
NSLStartNeighborhoodLookup |
||||
Header: | NSL.h | Carbon status: | Supported | |
Looks for neighborhoods.
NSLError NSLStartNeighborhoodLookup ( NSLRequestRef ref, NSLNeighborhood neighborhood, NSLClientAsyncInfo *asyncInfo );
On input, an NSLRequestRef created by previously calling NSLPrepareRequest.
On input, an NSLNeighborhood value created by previously calling NSLMakeNewNeighborhood. If neighborhood was created with a value of name that was NULL, NSLStartNeighborhoodLookup returns the first default neighborhood. If neighborhood was created with a value of name that is a name, NSLStartNeighborhoodLookup returns a related name. For example, if neighborhood was created with a value of name that is apple.com, NSLStartNeighborhoodLookup returns a subdomain of apple.com.
On input, a pointer to the asyncInfo structure in whose resultBuffer field NSLStartNeighborhood is to store neighborhood lookup results.
If the value of NSLError.theErr is noErr, NSLStartNeighborhoodLookup returned successfully. Possible errors are kNSLNotInitialized, kNSLSearchAlreadyInProgress, kNSLNoPluginsForSearch, kNSLBufferTooSmallForData, and kNSLNullNeighborhoodPtr.
The NSLStartNeighborhoodLookup function returns a neighborhood value that your application can use to define the scope of a subsequent service lookup.
For any NSLRequestRef, only one neighborhood or service lookup can be in progress at any one time.
When the NSL Manager calls your applications 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,
kNSLWaitingForContinue = 5
If the value of asyncInfo.searchState is kNSLSearchStatusBufferFull, your application should process the data returned in asyncInfo.resultBuffer.
If the value of asyncInfo.searchState is kNSLSearchStateOnGoing, the value of asyncInfo.alertInterval or asyncInfo.alertThreshold has been reached. Your notification routine should process the data returned in asyncInfo.resultBuffer and return to resume the lookup.
If the value of asyncInfo.searchState is kNSLSearchStateComplete and NSLStartNeighborhoodLookup does not return an error, the lookup is complete. Your application should process the data returned in asyncInfo.resultBuffer. If the value of asyncInfo.searchState is kNSLSearchStateComplete and NSLStartNeighborhoodLookup returns an error, the error is a fatal error and the lookup ends.
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 NSLStartNeighborhoodLookup 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 NSLStartNeighborhoodLookup returns an error code from one of the plug-ins. If the value of asyncInfo.searchState is kNSLSearchStateOngoing, the error code is not fatal. Your notification routine should process the data in the result buffer and return, thereby continuing the lookup.
NSLGetNextNeighborhood for information about processing the data in the result buffer.
© 2000 Apple Computer, Inc. (Last Updated 7/13/2000)