1 /* This file was written by Jim Kingdon, and is hereby placed
2 in the public domain. */
4 /* Bits of the SCC interface.
5 For paranoia's sake, I'm not using the same names as Microsoft.
6 I don't imagine copying a few names could be a credible copyright
7 case, but it seems safer to stick to only what is necessary for
10 Note that some of the descriptions here have a certain amount of
11 guesswork (for example, sometimes I have tried to translate to CVS
12 terminology without actually verifying that the item means what I
13 think it does). If you find errors, please let us know according to
14 the usual procedures for reporting CVS bugs. */
15 typedef long SCC_return;
16 #define SCC_return_success 0
17 #define SCC_return_unknown_project -2
18 /* The file is not under SCC control. */
19 #define SCC_return_non_scc_file -11
20 /* This operation is not supported. I believe this status can only
21 be returned from SccGet, SccAdd, SccRemove, SccHistory, or
22 SccQueryInfo. I'm not really sure what happens if it is returned
24 #define SCC_return_not_supported -14
25 #define SCC_return_non_specific_error -15
32 SCC_command_uncheckout,
38 SCC_command_properties,
42 /* Outproc codes, for second argument to outproc. */
43 #define SCC_outproc_info 1L
44 #define SCC_outproc_warning 2L
45 #define SCC_outproc_error 3L
46 /* Codes 4-7 relate to cancels and are only supported if the
47 development environment said so with SccSetOption. */
48 /* A status message, typically goes in something analogous to the emacs
49 minibuffer. For both this and SCC_outproc_nostatus, the development
50 environment returns SCC_outproc_return_cancelled if the user has
51 hit the cancel button. */
52 #define SCC_outproc_status 4L
53 /* Like SCC_outproc_status, but there is no message to report. */
54 #define SCC_outproc_nostatus 5L
55 /* Tell the development environment to offer a cancel button. */
56 #define SCC_outproc_cancel_on 6L
57 /* Tell the development environment to not offer a cancel button. */
58 #define SCC_outproc_cancel_off 7L
60 /* Return values from outproc. */
61 #define SCC_outproc_return_success 0L
62 #define SCC_outproc_return_cancelled -1L
63 typedef long (*SCC_outproc) (char *, long);
65 typedef BOOL (*SCC_popul_proc) (LPVOID callerdat, BOOL add_keep,
66 LONG status, LPCSTR file);
68 /* Maximum sizes of various strings. These are arbitrary limits
69 which are imposed by the SCC. */
70 /* Name argument to SccInitialize. */
71 #define SCC_max_name 31
72 /* Path argument to SccInitialize. */
73 #define SCC_max_init_path 31
74 /* Various paths many places in the interface. */
76 #define SCC_max_path _MAX_PATH
78 /* Status codes, as used by QueryInfo and GetEvents. */
79 /* This means that we can't get status. If the status is not
80 SCC_status_error, then the status is a set of bit flags, as defined by
81 the other SCC_status_* codes. */
82 #define SCC_status_error -1L
84 /* The following status codes are things which the development environment
85 is encouraged to check to determine things like whether to allow
87 /* The current user has the file checked out (that is, under "cvs edit").
88 It may or may not be in the directory where the development
89 environment thinks it should be. */
90 #define SCC_status_out_me 0x1000L
91 /* Should be set only if out_me is set. The file is checked out where
92 the development environment thinks it should be. */
93 #define SCC_status_out_here 2L
94 /* Some other user has the file checked out. */
95 #define SCC_status_out_someoneelse 4L
96 /* Reserved checkouts are in effect for the file. */
97 #define SCC_status_reserved 8L
98 /* Reserved checkouts are not in effect for the file. Multiple users
99 can edit it. Only one of SCC_status_reserved or SCC_status_nonreserved
100 should be set. I think maybe this flag should only be set if there
101 actually is more than one copy currently checked out. */
102 #define SCC_status_nonreserved 0x10L
104 /* The following flags are intended for the development environment to
105 display the status of a file. We are allowed to support them or not
107 /* The file in the working directory is not the latest version in the
108 repository. Like when "cvs status" says "Needs Checkout". */
109 #define SCC_status_needs_update 0x20L
110 /* The file is no longer in the project. I think this is the case where
111 cvs update prints "file xxx is no longer pertinent" (but I don't know,
112 there are other statuses involved with removed files). */
113 #define SCC_status_not_pertinent 0x40L
114 /* No checkins are permitted for this file. No real CVS analogue, because
115 this sort of thing would be done by commitinfo, &c. */
116 #define SCC_status_no_checkins 0x80L
117 /* There was a merge, but the user hasn't yet dealt with it. I think this
118 probably should be used both if there were conflicts on the merge and
119 if there were not (not sure, though). */
120 #define SCC_status_had_conflicts 0x100L
121 /* This indicates something has happened to the file. I suspect it mainly
122 is intended for cases in which we detect that something happened to the
123 file behind our backs. I suppose CVS might use this for cases in which
124 sanity checks on the CVSADM files fail, or in which the file has been
125 made read/write without a "cvs edit", or that sort of thing.
127 Or maybe it should be set if the file has been edited in the
128 normal fashion. I'm not sure. */
129 #define SCC_status_munged 0x800L
130 /* The file exists in several projects. In CVS I would suppose the
131 equivalent probably would be that several modules (using features
132 like -d) are capable of checking out a given file in the repository
133 in several locations. CVS has no current ability to give a different
134 status when that has happened, but it might be cool. */
135 #define SCC_status_several_projects 0x200L
136 /* There is a sticky tag or date in effect. */
137 #define SCC_status_stuck 0x400L
139 /* Bits to set in the caps used by SccInitialize. Most of these are
140 relatively straightforward, for example SCC_cap_QueryInfo is set to
141 indicate that the SccQueryInfo function is supported. */
142 /* CodeWright 5.00b and 5.00c seem to call SccQueryInfo regardless of whether
143 this bit is set in caps. */
144 #define SCC_cap_QueryInfo 0x80L
145 #define SCC_cap_GetProjPath 0x200L
146 #define SCC_cap_AddFromScc 0x400L
147 #define SCC_cap_want_outproc 0x8000L
149 /* These are command options. Some of them are specific to a particular
150 command, some of them are good for more than one command. Because many
151 values are reused for different commands, look at the listed commands
152 to see what a particular value means for a particular command. */
153 /* Recurse into directories. SccGet. */
154 #define SCC_cmdopt_recurse 2L
155 /* This means to get all the files in a directory. SccGet. */
156 #define SCC_cmdopt_dir 1L
157 /* Without this flag, after a checkin, files are normally not checked
158 out. This flag disables that handling, and if it is set files will
159 still be checked out after the checkin completes. SccCheckin, SccAdd. */
160 #define SCC_cmdopt_no_unedit 0x1000L
161 /* File is text. SccAdd. */
162 #define SCC_cmdopt_text 1L
163 /* File is binary. SccAdd. */
164 #define SCC_cmdopt_binary 2L
165 /* We are supposed to decide whether it is text or binary. We can use the
166 CVS wrappers stuff to decide based on the file name. Obviously, this
167 constant is just another way of saying that neither SCC_cmdopt_text nor
168 SCC_cmdopt_binary are set. SccAdd. */
169 #define SCC_cmdopt_auto 0L
170 /* Maintain only a head revision for the file, no history. SccAdd. */
171 #define SCC_cmdopt_only_one 4L
172 /* In addition to removing the file from the repository, also delete it
173 from the working directory. My guess is that development environments
174 would generally tend to pass this flag by default. SccRemove. */
175 #define SCC_cmdopt_retain_local 1L
176 /* Compare files in a case-insensitive fashion. SccDiff. */
177 #define SCC_cmdopt_case_insensitive 2L
178 /* Ignore whitespace in comparing files. SccDiff. */
179 #define SCC_cmdopt_ignore_all_space 4L
180 /* Instead of generating diffs, just say whether files are equal, based on
181 the file contents. SccDiff. */
182 #define SCC_cmdopt_compare_files 0x10L
183 /* Instead of generating diffs, just say whether files are equal. This may
184 use a checksum if we want, or if not, it can be the same as
185 SCC_cmdopt_compare_files. */
186 #define SCC_cmdopt_consult_checksum 0x20L
187 /* Instead of generating diffs, just say whether files are equal. This may
188 use a timestamp if we want, or if not, it can be the same as either
189 SCC_cmdopt_consult_checksum or SCC_cmdopt_compare_files. */
190 #define SCC_cmdopt_consult_timestamp 0x40L
192 /* Values for the flags argument to OpenProject. */
193 /* If this is set, and the development environment tries to open a project
194 which doesn't exist, then create it. */
195 #define SCC_open_autocreate 1L
196 /* If autocreate is not set, and the development environment tries to
197 open a project which doesn't exist, and may_prompt is set, we are
198 allowed to prompt the user to create a new project. If may_prompt
199 is not set, we should just return SCC_return_unknown_project and
200 not open the project. */
201 #define SCC_open_may_prompt 2L
203 /* Constants for SccSetOption. */
204 #define SCC_option_background 1L
205 /* If option is SCC_option_background, then val turns background
206 processing on or off. If it is off, we can, if we need to, queue
207 up events or something which won't disturb the development
209 # define SCC_option_background_yes 1L
210 # define SCC_option_background_no 0L
211 #define SCC_option_cancel 3L
212 /* If option is SCC_option_cancel, then val says whether the development
213 environment supports the SCC_outproc_* codes related to having the
214 development environment handle a cancel button. If this is not set,
215 we are allowed/encouraged to implement a cancel button ourselves. */
216 # define SCC_option_cancel_on 1L
217 # define SCC_option_cancel_off 0L
218 /* A SCC_option_* value of 10 has also been observed (I think from
219 CodeWright 5.00). I have no idea what it means; it isn't documented
220 by the SCC API from Microsoft (version 0.99.0823). */
222 /* The "void *context_arg" argument to most of the Scc* functions
223 stores a pointer to a structure that the version control system
224 gets to allocate, so it doesn't need any global variables. */
226 /* In addition to context_arg, most of the Scc* functions take a
227 "HWND window" argument. This is so that we can put up dialogs.
228 The window which is passed in is the IDE's window, which we
229 should use as the parent of dialogs that we put up. */
233 /* Return the version of the SCC spec, major version in the high word,
234 minor version in the low word. Recommended value is 0x10001 for
235 version 1.1 of the spec. */
236 extern LONG SccGetVersion (void);
238 /* Set up the version control system. This should be called before any
239 other SCC calls other than SccGetVersion. */
240 extern SCC_return SccInitialize
241 (/* The version control system should allocate the context argument
242 in SccInitialize and store a pointer to it in *contextp. */
245 HWND window, LPSTR caller,
246 /* Version control system should copy in the
247 name of the version control system here,
248 up to SCC_max_name bytes. */
251 /* Version control system should set *caps to indicate what it
252 supports, using bits from SCC_cap_*. */
255 /* Version control system should copy in a string here, that the
256 development environment can put places like a makefile to
257 distinguish this version control system from others. Up to
258 SCC_max_init_path bytes. */
261 /* Version control system should set these to the maximum size for
262 checkout comments and comments. I'm not sure whether existing
263 development environments tend to allocate fixed size arrays
264 based on the return length (I would recommend that a development
265 environment not do so, but that is a different question). */
266 LPDWORD co_comment_len,
267 LPDWORD comment_len);
269 /* The version control system should free any resources it has allocated,
270 including the context structure itself. */
271 extern SCC_return SccUninitialize (void *context_arg);
273 extern SCC_return SccOpenProject
274 (void *context_arg, HWND window, LPSTR user,
275 LPSTR project, LPSTR local_proj,
279 /* This is the function which the version control system can call
280 to ask the development environment to display output, or
281 (SCC_outproc)0 if the development environment doesn't support
282 the outproc feature. */
285 /* One or more of the SCC_open_* settings. */
288 extern SCC_return SccCloseProject (void *context_arg);
291 extern SCC_return SccGet
292 (void *context_arg, HWND window,
294 /* Files to get, where file_names is an array
295 of num_files names. */
296 /* As with all file names passed to us by the SCC, these file names
297 are absolute pathnames. I think they will tend to be paths
298 within the local directory specified by the local_proj argument
299 to SccOpenProject, although I don't know whether there are any
300 exceptions to that. */
304 /* Command options. */
310 extern SCC_return SccCheckout
311 (void *context_arg, HWND window,
313 /* Files to operate on, where file_names is an array of num_files
320 /* Command options. I'm not sure what command options, if any, are
321 defined for SccCheckout. */
327 extern SCC_return SccCheckin
328 (void *context_arg, HWND window,
330 /* Files to operate on, where file_names is an array of num_files
337 /* Command options. */
343 extern SCC_return SccUncheckout
344 (void *context_arg, HWND window,
346 /* Files to operate on, where file_names is an array of num_files
351 /* Command options. I'm not sure what command options, if any, are
352 defined for SccUncheckout. */
357 /* cvs add + cvs ci, more or less, I think (but see also
358 the "keep checked out" flag in options). */
359 extern SCC_return SccAdd
360 (void *context_arg, HWND window,
362 /* Files to operate on, where file_names is an array of num_files
369 /* Array of num_files command options, one for each file. */
374 /* cvs rm -f + cvs ci, I think. Should barf if SCC_REMOVE_KEEP
375 (or maybe just put the file there, as if the user had removed
376 it and then done a "copy <saved-file> <filename>". */
377 extern SCC_return SccRemove
378 (void *context_arg, HWND window,
380 /* Files to operate on, where file_names is an array of num_files
387 /* Command options. */
392 /* mv, cvs add, cvs rm, and cvs ci, I think. */
393 extern SCC_return SccRename
394 (void *context_arg, HWND window, LPSTR old_name,
397 /* If SCC_cmdopt_compare_files, SCC_cmdopt_consult_checksum, or
398 SCC_cmdopt_consult_timestamp, then we are supposed to silently
399 return a status, without providing any information directly to the
400 user. For no args or checksum (which we fall back to full compare)
401 basically a call to No_Diff or ? in the client case. For
402 timestamp, just a Classify_File. Now, if contents not set, then
403 want to do a cvs diff, and preferably start up WinDiff or something
404 (to be determined, for now perhaps could just return text via
406 extern SCC_return SccDiff
407 (void *context_arg, HWND window, LPSTR file_name,
409 /* Command options. */
414 /* cvs log, I presume. If we want to get fancier we could bring
415 up a screen more analogous to the tkCVS log window, let the user
416 do "cvs update -r", etc. */
417 extern SCC_return SccHistory
418 (void *context_arg, HWND window,
420 /* Files to operate on, where file_names is an array of num_files
425 /* Command options. I'm not sure what command options,
426 if any, are defined for SccHistory. */
431 /* cvs status, presumably. */
432 extern SCC_return SccProperties
433 (void *context_arg, HWND window, LPSTR file_name);
435 /* Not sure what this should do. The most obvious thing is some
436 kind of front-end to "cvs admin" but I'm not actually sure that
437 is the most useful thing. */
438 extern SCC_return SccRunScc
439 (void *context_arg, HWND window,
444 /* If the user invokes version-control-system-defined behavior
445 (typically by clicking an Advanced button in a dialog, e.g. the Get
446 dialog), and the user clicks on that button, then the development
447 environment calls SccGetCommandOptions. The version control system
448 interacts with the user and then sets *PROV_OPTIONSP to whatever it
449 wants. The development environment doesn't do anything with it,
450 but does pass it to the various commands as prov_options. If it
451 calls SccGetCommandOptions again, it will pass the same value (so
452 user choices from the previous "Advanced" click can serve as
455 Note that "provider options" (prov_options) are unrelated to
456 "command options" (SCC_cmdopt_*). */
458 extern SCC_return SccGetCommandOptions
459 (void *context_arg, HWND window,
460 enum SCC_command command,
461 void **prov_optionsp);
463 /* Not existing CVS functionality, I don't think.
464 Need to be able to tell user about what files
465 are out there without actually getting them. */
466 extern SCC_return SccPopulateList
467 (void *context_arg, enum SCC_command command,
472 SCC_popul_proc populate,
475 /* Command options. I'm not sure what command options,
476 if any, are defined for SccPopulateList. */
479 /* cvs status, sort of. */
480 extern SCC_return SccQueryInfo
483 LONG num_files, LPSTR *file_names,
485 /* This is an array of NUM_FILES entries. In each one
486 we store a SCC_status_* code. */
489 /* Like QueryInfo, but fast and for only a single file. For example, the
490 development environment might call this quite frequently to keep its
491 screen display updated. Supposed to only return cached status
492 information, not go to disk or anything. I assume that
493 QueryInfo and probably the usual calls like Get would cause
494 the version control system to cache the status in the first place. */
495 extern SCC_return SccGetEvents
496 (void *context_arg, LPSTR file_name,
498 /* Here the version control system stores the SCC_status_* code. */
501 LPLONG events_remaining);
503 /* This is where the user gives us the CVSROOT. */
504 extern SCC_return SccGetProjPath
505 (void *context_arg, HWND window, LPSTR user,
507 /* Version control system copies in the project name
508 here, up to SCC_max_path bytes. */
511 /* If allow_change, the version control system may copy
512 into this field, up to SCC_max_path bytes. */
515 /* Version control system copies into this field, up to
516 SCC_max_path bytes. */
519 BOOL allow_change, BOOL *new);
521 /* Pretty much similar to SccPopulateList. Not sure whether this also
522 involves getting the files, or whether the development environment will
523 typically call SccGet after this function. */
524 extern SCC_return SccAddFromScc
525 (void *context_arg, HWND window,
527 /* Version control system sets *files to the number of files and
528 *file_names to an array each element of which and contains the
529 name of one of the files. The names can be relative pathnames
530 (e.g. "foo.c"). If files is NULL, that means something different;
531 the version control system should free the memory that it allocated
536 /* This changes several aspects of how we interact with the IDE. */
537 extern SCC_return SccSetOption
539 /* One of the SCC_option_* codes. */
541 /* Meaning of this will depend on the value of option. */
544 /* New functions with CodeWright 5.00c: SccAddRef, SccRelease,
545 SccDiffToRev, SccLabel, SccLock and SccMerge. I don't have any