Release Notes for P4API, the Perforce C/C++ Application Programming Interface Version 2008.2 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 ------------------------------------------------------------------------- New functionality in 2008.2 #165501 Previously deleted ErrorIds have been resurrected so that clients built with a newer version of the api can handle errors from old servers. (Bug #30696) #164513 Tagged output for 'p4 labels' now includes Revision field for automatic labels. (SIR #30497) #160205 Tagged output for 'p4 clients' now includes LineEnd option. (SIR #30087) Bugs fixed in 2008.2 #175505 A spurious printf() call has been removed from Error::UnMarshall0(). (Bug #30280) ------------------------------------------------------------------------- New functionality in 2008.1 #152210 In response to customer requests, both the FileSys::Digest(), and FileSys::MakeLocalTemp() methods are now virtual. (SIR #28448, SIR #28980) #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 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. (Bug #28729) ------------------------------------------------------------------------- New functionality in 2007.3 #137472 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. (Bug #7546, 26830) #136840 The private member 'generic' of the Error class in error.h was changed to 'genericCode' to accommodate C#. (Bug #21738) #132645 Tagged output for 'p4 clients' now includes AltRoots and SubmitOptions. (Bug #18895, #23542) #130733 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. (Bug #25273) #130647 Tagged output for 'p4 groups' now includes the maxLockTime field for each user/group record. (Bug #25344, #23629) #130380 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. (Bug #20634) #130049,130052 The tagged output for 'p4 describe' and 'p4 changes' now contain 'oldChange' with the original changelist, if the changelist was automatically renumbered upon submit. (Bug #301, #5315) #130035 'p4 sync' has a new 'change' field in tagged output that displays the highest change number of the files being synced. (Bug #25343) #128872 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(). (Bug #25268) #128587 Enhanced the StrArray class to support editing and removal of individual elements. (Bug #25244) #124651 Added virtual destructor to KeepAlive class to remove compiler warnings. (Bug #20926) ------------------------------------------------------------------------- New functionality in 2007.2 #119531 'p4 where' has a new 'remap' field in tagged output that indicates that the mapping is a '+' mapping. #119231 The FileSys type member is now protected rather than private, allowing subclasses to get/set the type easily. (SIR #18070) #119366 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. (Bug #19881) #118804 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. (Bug #21294) #116379 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. (Bug #23661). ------------------------------------------------------------------------- New functionality in 2007.1 #110420 The 'p4 filelog' command has added the following new field to OutputStat: digest# -- file revision digest Bugs fixed since initial release #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. ------------------------------------------------------------------------- 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 transferred 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 since 2006.2/112639 (first release) #114374 * 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 causing 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. (Bug #23004) Bugs fixed in 2006.2 #105043 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). (Bug #21822) #104834 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. (Bug #21822) ------------------------------------------------------------------------- New functionality in 2006.1 #94587 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). (Bug #20225) #93935 Added StrOps::Upper() to match StrOps::Lower() for in place conversion of all characters to uppercase. (Bug #20187) #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 The fstat command has added the following new field to OutputStat: headModTime -- head rev mod time, if in depot (Bug #13802, #19872) Bugs fixed in 2006.1 #94815 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. (Bug #20294) #92564 Tagged output for 'p4 fix' would send spurious output to OutputInfo() in addition to OutputStat(). Now it correctly only sends data via OutputStat(). (Bug #19980) ------------------------------------------------------------------------- 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 separate from the other charset which applies to file names. The new content charset will default to match the other CharSet value. This is particularly 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 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. (Bug #9810) ------------------------------------------------------------------------- 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 independently 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 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 environment values. (Bug #15933) #71755 Some cases of FileSys object creation were not calling the clientUser->File method. Fixed. (Bug #15932) 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 suppresses 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 SetCwd(const char *) did not search for a new config file as documented and as SetCwd(StrPtr *) did. Fixed (Bug #14646) -------------------------------------------------------------------------- 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. -------------------------------------------------------------------------- New functionality in 2003.1 #41063 New command 'p4 monitor', see relnotes.txt for details. -------------------------------------------------------------------------- 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'. -------------------------------------------------------------------------- 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'. -------------------------------------------------------------------------- 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. -------------------------------------------------------------------------- New functionality in 2000.1 #17253 Tagged output added for 'p4 logger' and 'p4 counters'. -------------------------------------------------------------------------- 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.