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.

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().

ClientApi client;
Error e;

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

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

ClientApi client;
Error e;

printf( "Output is tagged depending on API or server level.\n" );
client.SetProtocol( "tag", "" ); // request tagged output
client.Init( &e );
client.Run( "info", &ui );
client.Final( &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( &e );
client.Run( "info", &ui );
client.Final( &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( &e );
client.Run( "info", &ui );
client.Final( &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 Helix Core 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.