bring cvs_1.12.13+real.orig.tar.gz into the game, with -I ! -I CVS -kb
[alioth/cvs.git] / windows-NT / SCC / pubscc.h
1 /* This file was written by Jim Kingdon, and is hereby placed
2    in the public domain.  */
3
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
8    the interface to work.
9
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
23    from other calls.  */
24 #define SCC_return_not_supported -14
25 #define SCC_return_non_specific_error -15
26
27 enum SCC_command
28 {
29         SCC_command_get,
30         SCC_command_checkout,
31         SCC_command_checkin,
32         SCC_command_uncheckout,
33         SCC_command_add,
34         SCC_command_remove,
35         SCC_command_diff,
36         SCC_command_history,
37         SCC_command_rename,
38         SCC_command_properties,
39         SCC_command_options
40 };
41
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
59
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);
64
65 typedef BOOL (*SCC_popul_proc) (LPVOID callerdat, BOOL add_keep,
66                                 LONG status, LPCSTR file);
67
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.  */
75 #include <stdlib.h>
76 #define SCC_max_path _MAX_PATH
77
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
83
84 /* The following status codes are things which the development environment
85    is encouraged to check to determine things like whether to allow
86    a checkin.  */
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
103
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
106    as we choose.  */
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.
126
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
138
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
148
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
191
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
202
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
208    environment.  */
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).  */
221
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.  */
225
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.  */
230
231 #include <windows.h>
232
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);
237
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.  */
243    void **contextp,
244
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.  */
249    LPSTR name,
250
251    /* Version control system should set *caps to indicate what it
252       supports, using bits from SCC_cap_*.  */
253    LPLONG caps,
254
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.  */
259    LPSTR path,
260
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);
268
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);
272
273 extern SCC_return SccOpenProject
274   (void *context_arg, HWND window, LPSTR user,
275    LPSTR project, LPSTR local_proj,
276    LPSTR aux_proj,
277    LPSTR comment,
278
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.  */
283    SCC_outproc outproc,
284
285    /* One or more of the SCC_open_* settings.  */
286    LONG flags);
287
288 extern SCC_return SccCloseProject (void *context_arg);
289
290 /* cvs get.  */
291 extern SCC_return SccGet
292   (void *context_arg, HWND window,
293
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.  */
301    LONG num_files,
302    LPSTR *file_names,
303
304    /* Command options.  */
305    LONG options,
306
307    void *prov_options);
308
309 /* cvs edit.  */
310 extern SCC_return SccCheckout
311   (void *context_arg, HWND window, 
312
313    /* Files to operate on, where file_names is an array of num_files
314       names.  */
315    LONG num_files,
316    LPSTR *file_names,
317
318    LPSTR comment,
319
320    /* Command options.  I'm not sure what command options, if any, are
321       defined for SccCheckout.  */
322    LONG options,
323
324    void *prov_options);
325
326 /* cvs ci.  */
327 extern SCC_return SccCheckin
328   (void *context_arg, HWND window,
329
330    /* Files to operate on, where file_names is an array of num_files
331       names.  */
332    LONG num_files,
333    LPSTR *file_names,
334
335    LPSTR comment,
336
337    /* Command options.  */
338    LONG options,
339
340    void *prov_options);
341
342 /* cvs unedit.  */
343 extern SCC_return SccUncheckout
344   (void *context_arg, HWND window,
345
346    /* Files to operate on, where file_names is an array of num_files
347       names.  */
348    LONG num_files,
349    LPSTR *file_names,
350
351    /* Command options.  I'm not sure what command options, if any, are
352       defined for SccUncheckout.  */
353    LONG options,
354
355    void *prov_options);
356
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,
361
362    /* Files to operate on, where file_names is an array of num_files
363       names.  */
364    LONG num_files,
365    LPSTR *file_names,
366
367    LPSTR comment,
368
369    /* Array of num_files command options, one for each file.  */
370    LONG *options,
371
372    void *prov_options);
373
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,
379
380    /* Files to operate on, where file_names is an array of num_files
381       names.  */
382    LONG num_files,
383    LPSTR *file_names,
384
385    LPSTR comment,
386
387    /* Command options.  */
388    LONG options,
389
390    void *prov_options);
391
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,
395    LPSTR new_name);
396
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
405    outproc).  */
406 extern SCC_return SccDiff
407   (void *context_arg, HWND window, LPSTR file_name,
408
409    /* Command options.  */
410    LONG options,
411
412    void *prov_options);
413
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,
419
420    /* Files to operate on, where file_names is an array of num_files
421       names.  */
422    LONG num_files,
423    LPSTR *file_names,
424
425    /* Command options.  I'm not sure what command options,
426       if any, are defined for SccHistory.  */
427    LONG options,
428
429    void *prov_options);
430
431 /* cvs status, presumably.  */
432 extern SCC_return SccProperties
433   (void *context_arg, HWND window, LPSTR file_name);
434
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,
440
441    LONG num_files,
442    LPSTR *file_names);
443
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
453    defaults).
454
455    Note that "provider options" (prov_options) are unrelated to
456    "command options" (SCC_cmdopt_*).  */
457
458 extern SCC_return SccGetCommandOptions
459   (void *context_arg, HWND window,
460    enum SCC_command command,
461    void **prov_optionsp);
462
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,
468
469    LONG num_files,
470    LPSTR *file_names,
471
472    SCC_popul_proc populate,
473    void *callerdat,
474
475    /* Command options.  I'm not sure what command options,
476       if any, are defined for SccPopulateList.  */
477    LONG options);
478
479 /* cvs status, sort of.  */
480 extern SCC_return SccQueryInfo
481   (void *context_arg,
482
483    LONG num_files, LPSTR *file_names,
484
485    /* This is an array of NUM_FILES entries.  In each one
486       we store a SCC_status_* code.  */
487    LPLONG status);
488
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,
497
498    /* Here the version control system stores the SCC_status_* code.  */
499    LPLONG status,
500
501    LPLONG events_remaining);
502
503 /* This is where the user gives us the CVSROOT.  */
504 extern SCC_return SccGetProjPath
505   (void *context_arg, HWND window, LPSTR user,
506
507    /* Version control system copies in the project name
508       here, up to SCC_max_path bytes.  */
509    LPSTR proj_name,
510
511    /* If allow_change, the version control system may copy
512       into this field, up to SCC_max_path bytes.  */
513    LPSTR local_proj,
514
515    /* Version control system copies into this field, up to
516       SCC_max_path bytes.  */
517    LPSTR aux_proj,
518
519    BOOL allow_change, BOOL *new);
520
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,
526
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
532       for file_names.  */
533    LONG *files,
534    char ***file_names);
535
536 /* This changes several aspects of how we interact with the IDE.  */
537 extern SCC_return SccSetOption
538   (void *context_arg,
539    /* One of the SCC_option_* codes.  */
540    LONG option,
541    /* Meaning of this will depend on the value of option.  */
542    LONG val);
543
544 /* New functions with CodeWright 5.00c: SccAddRef, SccRelease,
545    SccDiffToRev, SccLabel, SccLock and SccMerge.  I don't have any
546    details on them.  */