Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

C/C++ API Documentation | 2025.1

# ClientApi::SetProtocol( char *, char * )

Sets special protocols for the server to use.

Virtual? | No |
Class | `ClientApi` |
Arguments | `char *p` | the name of the variable to set
| `char *v` | the new value for that variable
Returns | `void` |

## Notes

`SetProtocol()` must be called before the connection is established with `Init()`.

The following variables are supported by `SetProtocol()`:

Variable | Meaning
--- | ---
`tag` | To enable tagged output (if tagged output for the command is supported by the server), set the `tag` variable to any value.
`specstring` | To enable specially formatted application forms, set the `specstring` to any value.
`api` | Set the `api` variable to the value corresponding to the level of server behavior your application supports.
`enableStreams` | To allow your application to work with stream depots, set the `enableStreams` variable to any value except 'no'. To explicitly disable streams support set `enableStreams` to 'no'.

By default, the value of the `api` protocol variable matches the version of the API with which you built your application. Under most circumstances, you do not need to set the protocol version from within your application. If you are concerned about changes in server behavior in different releases, you can manually set the `api` variable.

For instance, the "`p4 info`" command supports tagged output as of server release 2003.2, and changes to this format were made in 2004.2. Code requesting tagged output from "`p4 info`" that was compiled against the 2003.1 API library might break when running against a 2003.2 or newer server. To prevent this, set `api` to the value corresponding to the desired server release.

Command | Set api to | Tagged output supported?
--- | --- | ---
`info` | unset | Only if both server and API are at 2004.2 or greater
<=55 | Output is not tagged. Behaves like 2003.1 or earlier, even if the server supports tagged output. | =56
Output is tagged. Behaves like 2003.2. | =57 | Output is tagged. Behaves like 2004.1, 2004.2, or 2005.1.

See the table that lists the Protocol levels: server/client in the P4 Server Administration Documentation.

## Example

The following example demonstrates the use of `SetProtocol()` to enable tagged output. The result of this call is that the `ClientUser` object uses `OutputStat()` to handle the output, rather than `OutputInfo()`.

Copy

    ClientApi client;
    Error e;

    client.SetProtocol( "tag", "" );
    client.Init( &amp;e );
    client.Run( "branches", &amp;ui );
    client.Final( &amp;e );

The following example shows how to use a command group. See About command groups in the P4 Admin Documentation and the example for f_cmdgroup under Using structured logging > CommandStart in the P4 Server Administration Documentation.

Copy

    ClientApi client;
    client.SetProtocol("commandGroup", "myCmdGroup");

The following code illustrates how to ensure forward compatibility when compiling against newer versions of the P4 API for C/C++ or connecting to newer P4 Servers.

Copy

    ClientApi client;
    Error e;

    printf( "Output is tagged depending on API or server level.\n" );
    client.SetProtocol( "tag", "" ); // request tagged output
    client.Init( &amp;e );
    client.Run( "info", &amp;ui );
    client.Final( &amp;e );

    printf( "Force 2003.1 behavior regardless of API or server level.\n" );
    client.SetProtocol( "tag", "" );   //request tagged output
    client.SetProtocol( "api", "55" ); // but force 2003.1 mode (untagged)
    client.Init( &amp;e );
    client.Run( "info", &amp;ui );
    client.Final( &amp;e );

    printf( "Request 2003.2 output if API and server support it.\n" );
    client.SetProtocol( "tag", "");   // request tagged output
    client.SetProtocol( "api", "56"); // force 2003.2 mode (tagged)
    client.Init( &amp;e );
    client.Run( "info", &amp;ui );
    client.Final( &amp;e );

The "`p4 info`" command supports tagged output only in server release 2003.2 or later. In the example, the first `Run()` leaves `api` unset. If both the client API and P4 Server support tagged output for `p4 info`, the output is tagged. If you link the same code with the libraries from the 2003.1 release of the API, however, the first `Run()` returns untagged output even if connected to a 2003.2 server. By setting `api` to `55`, the second `Run()` ensures 2003.1 behavior regardless of API or server level. The third call to `Run()` supports 2003.2 behavior against a 2003.2 server and protects against future changes.

Your search for returned results