Protocol overview

The P4 API for C/C++ is built into P4 clients, such as the P4 command line client and the P4 Visual Client (P4V).

The P4ALTSYNC protocol is the communication protocol between the P4API and the P4ALTSYNC agent.

This functionality was introduced in the 2023.1 release of P4 API for C/C++ and requires a 2023.1 P4 Server.

The P4 API for C/C++ communicates with the P4ALTSYNC agent over either STDIO or named pipes defined by the value of the P4ALTSYNC environment variable:

  • If set to the path of an executable program or script, that executable will be launched and commands will be sent to the process’s STDIN and responses read from STDOUT
  • If set to a named pipe path (prefixed with pipe:), the pipe will be opened and commands written to the pipe and responses read from it.

All commands and responses are single-line JSON structures:

  • The commands always have an altSync key with the command as the value. Details are documented in the Protocol reference.

  • The responses always have a result key with a boolean success value (true is success) or string value of success, error or pass (see chmod, move and delete for details of pass). If the result is not success, an error string may be provided. Some commands may expect other fields too.

    Example success:

    {"result":true}

    Example failure:

    {"result":false,"error":"Unknown P4ALTSYNC command!"}

  • The protocol requires a newline \n at the end of each JSON string:

    {"altSync":"check","client":"vfs-c1","clientRoot":"e:\\temp\\vfs\\c1","port":"perforce:1666","user":"maria"}\n

Persistent hydration

You might want to support the persistent hydration of p4 hotfiles command, which requires mapping rules for that specific client workspace Directories on your machine where you work on file revisions that are managed by P4 Server..

In addition, as a convenience to the end users of your application, you might want to support the feature associated with the Don't free downloaded files on sync/revert checkbox that is explained at Introducing P4 VFS. This feature causes hydration within a given client workspace to persist across sessions for files that are sync'd and reverted, even if those files not mapped in the hotfile rules. This is also known as the "hydrated are hotfiles" feature.

To implement the "hydrated are hotfiles" feature, your altsync agent calls

p4 sync -k --sync-time=N

where the value of N must be the client's file modification time, after hydrating any placeholder files into the client workspace. Subsequent syncs and reverts will persist the hydration of the file in the client workspace.

To dehydrate the file to a placeholder, call the

p4 sync -k -q

command.

To learn more, see p4 hotfiles and p4 sync in the P4 CLI Reference.

Protocol support

The P4ALTSYNC JSON Protocol for writing your own client for a file virtualization service is fully supported. (The Technical Preview applies solely to the agent implementation that Perforce provides.)