![]() |
NSLStandardGetURL |
||||
Header: | NSL.h | Carbon status: | Supported | |
Displays a dialog box that allows the user to conduct a search.
OSStatus NSLStandardGetURL ( NSLDialogOptions *dialogOptions, NSLEventUPP eventProc, void *eventProcContextPtr, NSLURLFilterUPP filterProc, char *serviceTypeList, char **userSelectedURL );
On input, a pointer to an NSLDialogOptions structure whose fields specify the appearance of the dialog box. Call NSLGetDefaultDialogOptions to fill the fields of an NSLDialogOptions structure with the default dialog options. After calling NSLGetDefaultDialogOptions, you can customize the contents of the fields in the NSLDialogOptions structure.
On input, a value of type NSLEventUPP that points to an application-defined system event callback routine as described in NSLEventProcPtr or NULL. If eventProc is NULL, your application will not receive update events while the Select a Service dialog box is displayed.
On input, an untyped pointer to arbitrary data that the NSL Manager passes to the application-defined system event callback routine specified by eventProc. Your application can use contextPtr to associate any particular execution of your system event callback routine with any particular call of the NSLStandardGetURL function.
On input, a value of type NSLURLFilterUPP that specifies your application-defined filter routine , NSLEventProcPtr, or NULL if you do not have a filter routine. If specified, your filter routine will be called for each URL that is about to be displayed in the dialog box. If your filter routine returns TRUE, you have the option of specifying the name the URL is listed under by filling in the displayString parameter, which is passed as a parameter to your filter routine. If your filter routine returns FALSE, the URL is not displayed.
On input, a null-terminated string of tuples that describe the services that are to be searched for. The format of the tuples is as follows:
service-name,service-descriptor-list;
where service-descriptor-list is a comma-delimited list of services. For example, if you want to search for HTTP, HTTPS, and FTP, the value of serviceTypeList would be
"Web Servers,http,https;FTP Servers,ftp"
The result of setting serviceTypeList in this way would be a popup menu containing two items: Web Servers and FTP Servers. The result of a search performed on these two items would consist of the list of HTTP and HTTPS services that were found, followed by the list of FTP services that were found.
See the Discussion section below for information about using serviceTypeList to control the icon that is displayed for each service type.
On input, the address of a pointer to a string that will receive the URL that the user may select or enter. On output, if NSLStandardGetURL returns noErr, url contains the null-terminated URL the user selected. When your application no longer needs userSelectedURL, it should call NSLFreeURL NSLFreeURL to reclaim the memory associated with it.
A result code. If NSLStandardGetURL returns noErr, the user selected a URL and it is stored in the userSelectedURL parameter. If NSLStandardGetURL returns kNSLUserCanceled, the user clicked the Cancel button in the dialog box and the userSelectedURL parameter is empty.
The NSLStandardGetURL function displays a dialog box that allows the user to select the type of service that is to be searched for and the neighborhood in which the search is to be conducted. The calling application is responsible for specifying the list of services types, and the NSL Manager is responsible for displaying the neighborhoods, which it obtains by querying the NSL plug-ins that support the services specified by serviceTypeList.
The NSLStandardGetURL function displays a unique icon for each of the http, https, ftp, afp, lpr, LaserWriter, and AFPServer service descriptors and the same generic icon for any other service descriptor. You can use the serviceTypeList parameter to specify the display of an application-defined icon instead of an icon defined by the NSL Manager.
To cause the NSL Manager to display an application-defined icon, specify an icon suite resource id in the serviceTypeList parameter. For example, if the value of serviceTypeList is
Web Servers,http,https;Telnet Servers,telnet;NFS Servers,nfs,129
the NSL Managers unique icons will be displayed for HTTP and HTTPS services, the NSL Managers generic icon will be displayed for Telnet services, and the icon suite at resource ID 129 in your applications resource fork will be displayed for NFS services.
Be sure to dispose of the url parameter by calling NSLFreeURL when urlSelectedParameter is no longer needed.
Supported in Carbon. Available in Carbon 1.0.2 and later when NSL 1.1 or later is present.
© 2000 Apple Computer, Inc. (Last Updated 7/13/2000)