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