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. */ 547