1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
|
/*
File: NSL.h
Contains: Interface to API for using the NSL User Interface
Version: QuickTime 7.3
Copyright: (c) 2007 (c) 1997-2001 by Apple Computer, Inc., all rights reserved
Bugs?: For bug reports, consult the following page on
the World Wide Web:
http://developer.apple.com/bugreporter/
*/
#ifndef __NSL__
#define __NSL__
#ifndef __NSLCORE__
#include <NSLCore.h>
#endif
#ifndef __EVENTS__
#include <Events.h>
#endif
#if PRAGMA_ONCE
#pragma once
#endif
#ifdef __cplusplus
extern "C" {
#endif
#if PRAGMA_IMPORT
#pragma import on
#endif
#if PRAGMA_STRUCT_ALIGN
#pragma options align=mac68k
#elif PRAGMA_STRUCT_PACKPUSH
#pragma pack(push, 2)
#elif PRAGMA_STRUCT_PACK
#pragma pack(2)
#endif
typedef UInt32 NSLDialogOptionFlags;
enum {
kNSLDefaultNSLDlogOptions = 0x00000000, /* use defaults for all the options */
kNSLNoURLTEField = 0x00000001, /* don't show url text field for manual entry */
kNSLAddServiceTypes = 0x00000002, /* add the service type if a user enters an incomplete URL */
kNSLClientHandlesRecents = 0x00000004 /* Stops NSLStandardGetURL from adding the selection to the recent items folder */
};
struct NSLDialogOptions {
UInt16 version;
NSLDialogOptionFlags dialogOptionFlags; /* option flags for affecting the dialog's behavior */
Str255 windowTitle;
Str255 actionButtonLabel; /* label of the default button (or null string for default) */
Str255 cancelButtonLabel; /* label of the cancel button (or null string for default) */
Str255 message; /* custom message prompt (or null string for default) */
};
typedef struct NSLDialogOptions NSLDialogOptions;
typedef CALLBACK_API( Boolean , NSLURLFilterProcPtr )(char *url, Str255 displayString);
/* you can provide for calls to NSLStandardGetURL*/
typedef CALLBACK_API( void , NSLEventProcPtr )(EventRecord *newEvent, void *userContext);
typedef STACK_UPP_TYPE(NSLURLFilterProcPtr) NSLURLFilterUPP;
typedef STACK_UPP_TYPE(NSLEventProcPtr) NSLEventUPP;
/*
* NewNSLURLFilterUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( NSLURLFilterUPP )
NewNSLURLFilterUPP(NSLURLFilterProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
enum { uppNSLURLFilterProcInfo = 0x000003D0 }; /* pascal 1_byte Func(4_bytes, 4_bytes) */
#ifdef __cplusplus
inline DEFINE_API_C(NSLURLFilterUPP) NewNSLURLFilterUPP(NSLURLFilterProcPtr userRoutine) { return (NSLURLFilterUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppNSLURLFilterProcInfo, GetCurrentArchitecture()); }
#else
#define NewNSLURLFilterUPP(userRoutine) (NSLURLFilterUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppNSLURLFilterProcInfo, GetCurrentArchitecture())
#endif
#endif
/*
* NewNSLEventUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( NSLEventUPP )
NewNSLEventUPP(NSLEventProcPtr userRoutine);
#if !OPAQUE_UPP_TYPES
enum { uppNSLEventProcInfo = 0x000003C0 }; /* pascal no_return_value Func(4_bytes, 4_bytes) */
#ifdef __cplusplus
inline DEFINE_API_C(NSLEventUPP) NewNSLEventUPP(NSLEventProcPtr userRoutine) { return (NSLEventUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppNSLEventProcInfo, GetCurrentArchitecture()); }
#else
#define NewNSLEventUPP(userRoutine) (NSLEventUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppNSLEventProcInfo, GetCurrentArchitecture())
#endif
#endif
/*
* DisposeNSLURLFilterUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( void )
DisposeNSLURLFilterUPP(NSLURLFilterUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(void) DisposeNSLURLFilterUPP(NSLURLFilterUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); }
#else
#define DisposeNSLURLFilterUPP(userUPP) DisposeRoutineDescriptor(userUPP)
#endif
#endif
/*
* DisposeNSLEventUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( void )
DisposeNSLEventUPP(NSLEventUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(void) DisposeNSLEventUPP(NSLEventUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); }
#else
#define DisposeNSLEventUPP(userUPP) DisposeRoutineDescriptor(userUPP)
#endif
#endif
/*
* InvokeNSLURLFilterUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( Boolean )
InvokeNSLURLFilterUPP(
char * url,
Str255 displayString,
NSLURLFilterUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(Boolean) InvokeNSLURLFilterUPP(char * url, Str255 displayString, NSLURLFilterUPP userUPP) { return (Boolean)CALL_TWO_PARAMETER_UPP(userUPP, uppNSLURLFilterProcInfo, url, displayString); }
#else
#define InvokeNSLURLFilterUPP(url, displayString, userUPP) (Boolean)CALL_TWO_PARAMETER_UPP((userUPP), uppNSLURLFilterProcInfo, (url), (displayString))
#endif
#endif
/*
* InvokeNSLEventUPP()
*
* Availability:
* Non-Carbon CFM: available as macro/inline
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API_C( void )
InvokeNSLEventUPP(
EventRecord * newEvent,
void * userContext,
NSLEventUPP userUPP);
#if !OPAQUE_UPP_TYPES
#ifdef __cplusplus
inline DEFINE_API_C(void) InvokeNSLEventUPP(EventRecord * newEvent, void * userContext, NSLEventUPP userUPP) { CALL_TWO_PARAMETER_UPP(userUPP, uppNSLEventProcInfo, newEvent, userContext); }
#else
#define InvokeNSLEventUPP(newEvent, userContext, userUPP) CALL_TWO_PARAMETER_UPP((userUPP), uppNSLEventProcInfo, (newEvent), (userContext))
#endif
#endif
#if CALL_NOT_IN_CARBON || OLDROUTINENAMES
/* support for pre-Carbon UPP routines: New...Proc and Call...Proc */
#define NewNSLURLFilterProc(userRoutine) NewNSLURLFilterUPP(userRoutine)
#define NewNSLEventProc(userRoutine) NewNSLEventUPP(userRoutine)
#define CallNSLURLFilterProc(userRoutine, url, displayString) InvokeNSLURLFilterUPP(url, displayString, userRoutine)
#define CallNSLEventProc(userRoutine, newEvent, userContext) InvokeNSLEventUPP(newEvent, userContext, userRoutine)
#endif /* CALL_NOT_IN_CARBON */
/* <--- function returns OSStatus of the operation. noErr will be returned if valid, kNSLUserCanceled will be returned if the user cancels */
/* ---> dialogOptions */
/* ---> eventProc */
/* ---> eventProcContextPtr */
/* ---> filterProc */
/* ---> serviceTypeList */
/* <--- userSelectedURL */
/* NSLDialogOptions* dialogOptions */
/*
dialogOptions is a user defined structure defining the look, feel and operation of NSLStandardGetURL dialog
default behavior can be achieved by passing in a pointer to a structure that has been filled out by a previous
call to NSLGetDefaultDialogOptions or by passing in NULL.
*/
/* NSLEventUPP eventProc */
/*
the eventProc is a callback NSLURLFilterUPP that will
get called with Events that the dialog doesn't handle. If you pass in nil,
you won't get update events while the NSLStandardGetURL dialog is open.
*/
/* void* eventProcContextPtr */
/* you can provide a pointer to some contextual data that you want to have sent to your eventProc filter*/
/* NSLURLFilterProcPtr filterProc */
/*
the filter param is a callback NSLURLFilterUPP that
will get called (if not nil) for each url that is going to be displayed in
the dialog's result list. A result of false will not include the url for the
user to select from. You also have the option of handling the way the url looks
in the dialog listing by copying the preferred name into the displayString
parameter. (If left alone, NSLStandardGetURL dialog will strip the service type
portion off the url).
*/
/* char* serviceTypeList */
/*
the serviceTypeList parameter is a null terminated string that will
directly affect the contents of the services popup in the dialog.
The structure of this string is a set of tuples as follows:
Name of ServiceType as to be represented in the popup followed by
a comma delimted list of service descriptors (ie http,https) that will
used in the search of that type. Each comma delimited tuple is delimited
by semi-colons.
*/
/*
For example:
If you want to search for services of type http (web), https (secure web),
and ftp, you could pass in the string "Web Servers,http,https;FTP Servers,ftp".
This would result in a popup list with two items ("Web Servers" and "FTP Servers")
and searches performed on them will provide results of type http and https for the
first, and ftp for the second.
*/
/*
Results list Icons:
NSLStandardGetURL provides icons in its listings for the following types:
"http", "https", "ftp", "afp", "lpr", "LaserWriter", "AFPServer"
any other types will get a generic icon. However, you can provide icons
if you wish by including an '#ics8' resource id at the end of your comma
delimited list. The dialog will then use that icon if found in its results
list. This icon will be used for all types in a tuple.
For example:
The param "Web Servers,http,https;Telnet Servers,telnet;NFS Servers,nfs,129"
would result in lists of http and https services to be shown with their default
icons, telnet servers would be shown with the default misc. icon and nfs
servers would be shown with your icon at resource id 129.
*/
/* char** url */
/*
pass in the address of a char* and it will point to the resulting url. If the user
cancels (the function returns false), the pointer will be set to nil. If the function
returns true (user selected a url), then you must call NSLFreeURL on the pointer when
you are done with it.
*/
/*
Call this to have the user select a url based service from a dialog.
Function takes on input an optional filter proc, a serviceTypeList, and an address to a Ptr.
Function sets the value of the Ptr to a newly created c-style null terminated string
containing the user's choice of URL.
*/
/*
* NSLStandardGetURL()
*
* Availability:
* Non-Carbon CFM: in NSLPPCLib 1.1 and later
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
NSLStandardGetURL(
NSLDialogOptions * dialogOptions, /* can be NULL */
NSLEventUPP eventProc, /* can be NULL */
void * eventProcContextPtr, /* can be NULL */
NSLURLFilterUPP filterProc, /* can be NULL */
char * serviceTypeList,
char ** userSelectedURL);
/*
* NSLGetDefaultDialogOptions()
*
* Availability:
* Non-Carbon CFM: in NSLPPCLib 1.1 and later
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSStatus )
NSLGetDefaultDialogOptions(NSLDialogOptions * dialogOptions);
/* <--- function returns null (useful for setting variable at same time as freeing it */
/* ---> url is memory created by a call to NSLStandardGetURL */
/*
* NSLFreeURL()
*
* Availability:
* Non-Carbon CFM: in NSLPPCLib 1.1 and later
* CarbonLib: in CarbonLib 1.0 and later
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( char * )
NSLFreeURL(char * url);
/* <--- function returns kNSLErrNullPtrError, file mgr errors, or resource mgr errors */
/* ---> folderSelectorType is one of the well-known folders defined in Folders.h */
/* ---> url is any valid url */
/* ---> userFriendlyName is used for the file name and the display name (in the UI) */
/*
* NSLSaveURLAliasToFolder()
*
* Availability:
* Non-Carbon CFM: in NSLPPCLib 1.1 and later
* CarbonLib: not available
* Mac OS X: in version 10.0 and later
*/
EXTERN_API( OSErr )
NSLSaveURLAliasToFolder(
OSType folderSelectorType,
const char * url,
const char * userFriendlyName);
#if PRAGMA_STRUCT_ALIGN
#pragma options align=reset
#elif PRAGMA_STRUCT_PACKPUSH
#pragma pack(pop)
#elif PRAGMA_STRUCT_PACK
#pragma pack()
#endif
#ifdef PRAGMA_IMPORT_OFF
#pragma import off
#elif PRAGMA_IMPORT
#pragma import reset
#endif
#ifdef __cplusplus
}
#endif
#endif /* __NSL__ */
|