Release Notes for P4API, the Perforce C/C++ Application Programming Interface Version 2009.1 Introduction For details about installing and using the Perforce C/C++ API, refer to the API User's Guide, posted on the Perforce Web site at: http://www.perforce.com/perforce/technical.html ------------------------------------------------------------------------- Major new functionality in 2009.1 #197669 (Bug #33482) Tagged output for 'p4 opened' now includes the field haveRev. #187587 (Bug #32338) Tagged output for 'p4 describe' for submitted changes now includes fields for digest and fileSize for files in the change if those values have already been computed. #177023 The 'p4 move' command introduces new tagged fieldnames (used by fstat and opened). movedFile -- name in depot of moved to/from file movedRev -- head revision of moved file Also the tagged field 'action' has two new values, 'move/add' and 'move/delete'. This new value will appear in the the tagged output of many commands. For backwards compatability the client may force these new actions to the less descriptive 'add' and 'delete' values by setting the 'api' protocol level to 64 or less. Bugs Fixed in 2009.1 #205388 Server change 205388 (see release notes) potentially changes the output of the 'p4 filelog -m -i' command by fixing a long standing revision bug. If your application relies on the old incorrect behaviour, either use the 2008.2 client api or get the old behaviour by setting protocol variable "api" to "64" (2008.2). For the command line 'p4' executable the output can be frozen to 2008.2 output by using -Zapi=64. #200645 (Bug #33896) Tagged output (or other than C++ apis) from 'p4 jobs' against a unicode server with user defined fields which are not translateable into the P4CHARSET could crash the p4 command line or other p4 api programs. #184408 (Bug #28944) The close-on-exec flag is now set on the client/server socket where available. #179833 (Bug #31215) Using the SetBreak callback support when the file descriptor communicating with the server is higher than FD_SETSIZE could cause api crashes or data smashes. Fixed. ------------------------------------------------------------------------- ------------------------------------------------------------------------- Major new functionality in 2008.2 #165501 (Bug #30696) Previously deleted ErrorIds have been resurrected so that clients built with a newer version of the api can handle errors from old servers. #164513 (Bug #30497) Tagged output for 'p4 labels' now includes Revision field for automatic labels. #160205 (Bug #30087) Tagged output for 'p4 clients' now includes LineEnd option. ------------------------------------------------------------------------- ------------------------------------------------------------------------- Major new functionality in 2008.1 #152210 (Bug #28448, #28980) In response to customer requests, both the FileSys::Digest(), and FileSys::MakeLocalTemp() methods are now virtual. #149295 The logic that the server uses to combine and interpret views is now available client-side and exposed in the new MapApi class, defined in mapapi.h. Client developers may use this new class to simulate the behavior of client views, protections, branch views, and combinations thereof without running server commands. Bugs Fixed in 2008.1 #153603 (Bug #28729) Unicode mode clients on Windows platforms running with a P4CHARSET of utf8 could get error messages which contain a mix of utf8 and a system character set. With this fix, the system error message portion should also be in utf8. ------------------------------------------------------------------------- ------------------------------------------------------------------------- Major new functionality in 2007.3 #137472 (Bug #7546, 26830) Trigger standard output is now passed to the client on success (via OutputMsg()). Clients may override the ClientUser::Message() method to handle this output by testing for this informational message (E_INFO) using Error::CheckId( MsgServer::TriggerOutput ). Note that '# include "msgserver.h"' is needed in the source file that references this server message. Clients may force the old behavior by setting the 'api' protocol level to 61 or less. #136840 (Bug #21738) The private member 'generic' of the Error class in error.h was changed to 'genericCode' to accomodate C#. #132645 (Bug #18895, #23542) Tagged output for 'p4 clients' now includes AltRoots and SubmitOptions. #130733 (Bug #25273) Tagged output for 'p4 groups -v [group]' includes new field 'isValidUser' which indicates whether the user or subgroup member is a real user or group. #130647 (Bug #25344, #23629) Tagged output for 'p4 groups' now includes the maxLockTime field for each user/group record. #130380 (Bug #20634) Tagged output for 'p4 info' run through the proxy now shows the proxy version string (proxyVersion). Note that this also requires the 2007.3+ version of the proxy. #130049,130052 (Bug #301, #5315) The tagged output for 'p4 describe' and 'p4 changes' now contain 'oldChange' with the original changelist, if the changelist was automatically renumbered upon submit. #130035 (Bug #25343) 'p4 sync' has a new 'change' field in tagged output that displays the highest change number of the files being synced. #128872 (Bug #25268) Added GetErrors method to ClientApi class. GetErrors() provides a count of errors returned by the server and can be used to determine if a call to Run() succeeds or fails without calling Final(). #128587 (Bug #25244) Enhanced the StrArray class to support editing and removal of individual elements. #124651 (Bug #20926) Added virtual destructor to KeepAlive class to remove compiler warnings. ------------------------------------------------------------------------- ------------------------------------------------------------------------- Major functionality in 2007.2 #119531 'p4 where' has a new 'remap' field in tagged output that indicates that the mapping is a '+' mapping. #119231 (Bug #18070) The FileSys type member is now protected rather than private, allowing subclasses to get/set the type easily. #119366 (Bug #19881) Restructure the API distribution.The new structure puts all of the header files under an "include/p4/" directory structure and the libraries in a "lib/" directory. For existing programs, update the '-I', '-L' and '-l' compile and link lines to these new locations. If there is a name conflict, then use the "#include " syntax for all references to the p4api headers and change the '-I' line to the "include/" directory. #118804 (Bug #21294) Added 'strarray.h' header to distribution. FileSys::ScanDir returns this type so this header provides the information needed in order to use this return result. #116379 (Bug #23661) FileSys::Path() is now a virtual function, with Name() merely calling Path(). With the virtual Set() this makes it easier to subclass FileSys for the purpose of adjusting filesystem path names. ------------------------------------------------------------------------- ------------------------------------------------------------------------- Major new functionality in 2007.1 #110420 The 'p4 filelog' command has added the following new field to OutputStat: digest# -- file revision digest Bugs fixed in 2007.1 #119595 FileSys::CheckFile used to check for missing symlinks would report a symlink was missing if the target of the symlink was missing. Fixed. #118729 Forcing a merge to resolve via 'accept merge' when conflict markers are present caused improper tamper check results in GUI programs. Fixed. ------------------------------------------------------------------------- ------------------------------------------------------------------------- Major new functionality in 2006.2 #107305 The FileSys::Stat method on FileSys objects which were created as symbolic links now behaves identically as other normal FileSys objects. Previously, the Stat method on symlink typed FileSys objects would only return 0 or FSF_EXISTS. Now, if you want to check for a symlink existing, you should check for FSF_SYMLINK, as the FSF_EXISTS bit will indicate if the symlink points to an existing file not regarding the symlink itself. #100486 The 'p4 sync' command has added the following new fields to OutputStat: fileSize -- size of file to be transfered totalFileSize -- total file transfer size * totalFileCount -- total file count * * These two fields are sent only with the first OutputStat call. #98998 The zlib library within the api now has symbols prefixed with 'PZ_' to allow linking different versions of zlib into api programs without conflict. This may require api programs supply their own zlib instead of linking with the one in the api. Bugs fixed in 2006.2 #114374 (Bug #23004) * The dialog parameter of the SetTrans call to enable client unicode mode was ignored if the output and content parameters differed from each other. In this case dialogs were not translated or verified causeing whatever information to be stored in the server metadata. With the server in unicode mode, this data is assumed to be utf8. Fixed so that the dialog parameter is honored and if it is not given it defaults to the same as the output parameter. #105043 (Bug #21822) Errors encountered from Spec::Spec(const char *string, const char *cmt, Error *e) will no longer crash the server. Note that the definition has been widened to include Error* e as the last parameter. Now callers must pass the Error *e and handle the error upon return, when previously an error from this call would simply abort the client (and possibly the server). #104834 (Bug #21822) Errors encountered from PathSys::Create( int ) will no longer crash the server. Furthermore, the method with this signature is no longer public to the api since it was never fully supported in the api. Api users must use one of the other public PathSys::Create() methods which are fully supported with error handling and better defined parameters. ------------------------------------------------------------------------- ------------------------------------------------------------------------- Major new functionality in 2006.1 #94587 (Bug #20225) New ClientMerge::DetectResolve() allows access to the ClientMerge::Resolve() functionality that compares the edited result against the generated yours/theirs/merge to produce a default action (accept your, theirs, merge, edit). #93935 (Bug #20187) Added StrOps::Upper() to match StrOps::Lower() for in place conversion of all characters to uppercase. #93388,93387 Use of the 'const_char #define has been removed from the API and all client code should be updated to reflect this change. To update code to compile against this version of the API, search for 'const_char' and replace with 'const char'. Additionally, compile time errors will be generated for invalid use of 'char' instead of 'const char' for derived classes. #91869 (Bug #13802, #19872) The fstat command has added the following new field to OutputStat: headModTime -- head rev mod time, if in depot Bugs fixed in 2006.1 #94815 (Bug #20294) Tagged output for 'p4 jobs' now shows the normalized values of the "Job" field instead of the raw values. Now guis can use this value without modification when its value is used in forms. #92564 (Bug #19980) Tagged output for 'p4 fix' would send spurious output to OutputInfo() in addition to OutputStat(). Now it correctly only sends data via OutputStat(). ------------------------------------------------------------------------- ------------------------------------------------------------------------- Major new functionality in 2005.2 #85237 Many more commands now support tagged output. By setting the value of "api" to "57" (2005.1) the application will not get tagged output when compiled with 2005.2 API and run against a 2005.2 server. New commands with tagged output are as follows: monitor (change 75907) have (change 75926) depots (change 75945) reviews (change 75981) branch -o (change 77156) change -o (change 77156) client -o (change 77156) job -o (change 77156) label -o (change 77156) trigger -o (change 77156) user -o (change 77156) add (change 77729) edit (change 77729) delete (change 77729) verify (change 78033) reopen (change 78136) lock (change 78192) unlock (change 78192) sync (change 78329) labelsync (change 79507) integrate (change 80315) revert (change 80316) review (change 80826) fix (change 81204) attribute (change 82886) interchanges (change 83150) counter (change 83810) obliterate (change 84782) diff* (change 84951) submit (change 85142) resolve* (change 85237) Note that 'resolve' and 'diff' are not fully tagged. Only 'resolve -n', 'resolve -ay', and 'resolve -at' are tagged because other resolve options generate output from the client which cannot be tagged. Only the summary data of 'diff' is tagged. The actual diff output is not tagged because the diffs originate from the client (ClientUser::Diff()). For tagged diff output, the summary data is passed to OutputStat(), but the actual diffs are generated and subsequently output by the client in its version of ClientUser::Diff(). #84505 The ClientApi::GetConfig() method allows client applications to find out the name of the P4CONFIG file found by the last Enviro::Config() call. If none was found,, "noconfig" is returned. #84256 The FileSys class has a new functions to set and get a character set for file contents seporate from the other charset which applys to file names. The new content charset will default to match the other CharSet value. This is paticularly important for utf16 support if your application can not automatically detect utf16 content in files. #83222 The fstat command has added the following new field to OutputStat: isMapped -- set if mapped client file is synced. #82166 The ClientApi::SetVersion() method allows client applications to set a version string to be used in 'p4 monitor show -e' and server log output. #77906 To allow completely customized file handling by API-based clients, some previously non-virtual methods of the FileSys class are now virtual. The affected methods are: StrArray *ScanDir( Error *e ) void MkDir( const StrPtr &p, Error *e ) void RmDir( const StrPtr &p, Error *e ) #75604 The CharSetApi class has a new function which gives the string name of a CharSet enum value. Returns NULL if the enum value is not valid. Bugs fixed in 2005.2 #82726 (Bug #9810) Compiling Windows clients with our API using VC.Net will no longer generate compiler warnings when set to warning level 4. Now one may set "Treat warnings as errors" within VC.Net, and the API will not cause compilation to fail. ------------------------------------------------------------------------- ------------------------------------------------------------------------- Major new functionality in 2005.1 #72726 It is now possible to set the location of the users ticketfile (P4TICKETS) using the new function ClientApi::SetTicketFile(). #71843 FileSys objects can independantly set their character set overriding the character set set by SetTrans. With this it is possible (but not easy) to maintain multiple server connections to a mix of unicode and non-unicode servers by calling SetTrans before connecting and having clientUser objects which set the character set of FileSys objects correctly for each connection. #70078,69880,69639,68917 'p4 fstat' has a new option '-Rt', this restricts output to non-deleted head revisions. The fstat command also adds the following new fields to OutputStat: desc# -- change description (requires '-e #changelist') otherChange# -- changelist, if opened by someone else digest# -- file digest (requires '-Ol') Bugs fixed in 2005.1 #72406 (Bug #15933) On Windows clients operating with character set UTF8 use Unicode Windows APIs to get user related environment variables and allow Perforce variables to supply these enviroment values. #71755 (Bug #15932) Some cases of FileSys object creation were not calling the clientUser->File method. Fixed. ------------------------------------------------------------------------- ------------------------------------------------------------------------- Major new functionality in 2004.2 #58453 'p4 groups' supports tagged output. By setting the value of "api" to "56" (2003.2) the application will not get tagged output when compiled with 2004.2 API and run against a 2004.2 server. #58420 'p4 where' supports tagged output. By setting the value of "api" to "56" (2003.2) the application will not get tagged output when compiled with 2004.2 API and run against a 2004.2 server. #58146 'p4 diff2' supports tagged output. By setting the value of "api" to "56" (2003.2) the application will not get tagged output when compiled with 2004.2 API and run against a 2004.2 server. Note tagged diff2 output supresses the actual diff of files and only supplies summary information. #58026,53703,53137 'p4 fstat' has new options '-e #changelist', '-Rr', '-Ru', '-Rn' and '-Or'. The flag '-Or' will add these extra fields to OutputStat: resolveAction# -- pending integration record action resolveBaseFile# -- pending integration base file resolveBaseRev# -- pending integration base rev resolveFromFile# -- pending integration from file resolveStartFromRev# -- pending integration from start rev resolveEndFromRev# -- pending integration from end rev Also the new field 'type' will be displayed, if the file is opened on the current client. #57553 New command 'p4 tag', see relnotes.txt for details. #53478 New commands 'p4 login' and 'p4 logout' allow the user to create an authorized connection to the Perforce Server. See relnotes.txt for details. #53302 'p4 users' tagged output will include the field "Password" with a value "enabled" if the user has a password set. #53184 'p4 info' tagged output now has some extra fields. These fields are only output if their functionality is enabled. name value ---- ----- password enabled (if the P4USER is a valid user and password set) monitor enabled (if the monitor counter is set) security enabled (if the security counter is set) unicode enabled (if the unicode counter is set) #52652 Server change 50435 (see release notes) potentially changes the output of the 'p4 diff2' command by fixing a long standing format bug. If your application relies on the old incorrect behaviour, either use the 2003.2 client api or get the old behaviour by setting protocol variable "api" to "56" (2003.2). For the command line 'p4' executable the output can be frozen to 2003.2 output by using -Zapi=56. #51751 'p4 monitor' now sports a '-e' flag which displays extra environment information such as the identity of the client application. To set the identity of a client application the new function ClientApi::SetProg() can be used. e.g. Client client; Error e; client.Init( &e ); client.SetProg( "MyApp" ); Bugs fixed in 2004.2 #62240 (Bug #14646) SetCwd(const char *) did not search for a new config file as documented and as SetCwd(StrPtr *) did. Fixed. -------------------------------------------------------------------------- -------------------------------------------------------------------------- Major new functionality in 2003.2 #55709 On Windows platforms which have native Unicode support operations which affect the registry will now use Unicode registry operations if the client is operating in Unicode mode with output translation (set via SetTrans) set to UTF8. Prior to this change the registry was set improperly by such applications i.e. P4Win in Unicode mode. After this change it will be possible for P4Win to set registry values for variables like P4USER to values which other clients might not be able to support i.e. values which mix characters from incompatible character sets. #49768 New protocol variable "api" can freeze expected server output to a particular server version. Typically the version of the API you link with dictates any difference in output you may receive from the server. This protocol variable allows you to link with the latest API but avoid having to code for new output format by "freezing" the output behaviour of the server against a particular API release. For example change 46402 below will change the output of the info command if your application sets the "tag" protocol variable. By setting the value of "api" to "55" (2003.1) the application will not get tagged output when compiled with 2003.2 API and run against a 2003.2 server. #46402 'p4 info' supports "tagged" output. #45056 Character set translations exposed to the api: The ClientApi::SetTrans method sets up client character set translations and must be called before connecting to a P4D operating in I18N mode. (i.e. call SetTrans before calling Init) See i18nnotes.txt for more information on I18N mode. The values of arguments to SetTrans are the CharSet enum defined in i18napi.h and you will need to cast that enum into an integer before calling SetTrans. The arguments to the SetTrans method are: output - translation of message output and input arguments content - translation of unicode file contents fnames - translation of file system path names dialog - translation of form specification dialogs A value of zero (0) for all but the output argument will choose a translation based on the other arguments. The simplest and most common usage is to only supply an output character set and all others will follow that. The CharSetApi::Lookup method returns -1 cast into enum CharSet if it does not recognize the argument string as a supported charset. -------------------------------------------------------------------------- -------------------------------------------------------------------------- Major new functionality in 2003.1 #41063 New command 'p4 monitor', see relnotes.txt for details. -------------------------------------------------------------------------- -------------------------------------------------------------------------- Major new functionality in 2002.2 #35149 New command 'p4 annotate', see relnotes.txt for details. #33571 Tagged output support for 'p4 resolved' and fixes in 'p4 describe'. -------------------------------------------------------------------------- -------------------------------------------------------------------------- Major new functionality in 2002.1 #28136 Previously, tagged output for commands were added without regard to the version of the client, but that broke old applications that set the 'tag' protocol and expected it only for commands that produced tagged output at the time. This practice was continued with the introduction of tagged output for 'p4 files/print' and 'p4 integrated' for 2002.1. Now the server checks the version that the client was compiled with and reverts to non-tagged output if the client is pre-2002.1. Applications only need to handle the new tagged output in 2002.1 if they are linked against a 2002.1 API. #26627 Cleanup of the distribution tar file. #26609 Tagged output added for 'p4 files' and 'p4 integrated'. -------------------------------------------------------------------------- -------------------------------------------------------------------------- Major new functionality in 2000.2 #19028 New file samplemain.cc included in the api tar file to demonstrate its usage. #18965 API users wishing to intercept client workspace file I/O are now able to by replacing "FileSys *ClientUser::File()" in a ClientUser subclass. -------------------------------------------------------------------------- -------------------------------------------------------------------------- Major new functionality in 2000.1 #17253 Tagged output added for 'p4 logger' and 'p4 counters'. -------------------------------------------------------------------------- -------------------------------------------------------------------------- Major new functionality in 98.2 #8235 Introduced the StrDict interface that can be used where ever a simple var/value dictionary must be passed around.