index.html

<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
 
<head>
<title>P4COM - COM Interface to Perforce C++ API on Windows</title>
 
<style TYPE="text/css">
<!--
 
BODY {font: 12px/16px verdana, arial, sans-serif !important;
            text-align: left;
            margin-left: 2cm;
            color:#000000 !important;}
 
.cell {font: 12px/16px verdana, arial, sans-serif !important;
            text-align: left;
            color:#000000 !important;}
 
TD {font: 12px/16px verdana, arial, sans-serif !important;
            text-align: left;
            color:#000000 !important;}
            
H1 {font: 18px/18px verdana, arial, sans-serif !important;
            text-align: left;
            color:#333333 !important;}
 
H2 {font: 18px/18px verdana, arial, sans-serif !important;
            text-align: left;
            color:#333333 !important;
            font-weight: bold;
            margin-bottom: 14px}
 
H3 {font: 14px/14px verdana, arial, sans-serif !important;
            text-align: left;
            color:#333333 !important;
            font-weight: bold;
            margin-bottom: 14px}
pre {
    border-right: #646464 1px solid;
    padding-right: 0.5em;
    border-top: #646464 1px solid;
    padding-top: 0.5em;
    border-left: #646464 1px solid;
    padding-left: 0.5em;
    border-bottom: #646464 1px solid;
    padding-bottom: 0.5em;
    white-space: pre;
    background-color: #f6e6e6;
    color: black;
    margin-left: 1em;
    width: 90%;
    display: table;
    font-size: 100%;
}
 
-->
</style>
 
</head>
 
<body>
 
<h1><a name="top"></a>P4COM - COM Interface to Perforce C++ API on Windows</h1>
<p>p4com is contributed by Robert Cowham of Vaccaperna Systems Ltd. Robert is a
<a href="http://public.perforce.com/guest/robert_cowham/pcp.html">Perforce 
Consulting Partner and Certified Trainer</a> (contact me via that page).</p>
<p>It is a COM component that can be used on Windows by a wide variety of 
languages to interface to Perforce in a nicer way than spawning p4.exe and 
parsing the output.</p>
<h4 class="dtH4">P4COM&nbsp; vs. P4API.Net/P4.Net</h4>
<p><a href="http://www.perforce.com/perforce/doc.current/user/p4api.netnotes.txt">
P4API.Net</a> is entirely managed code and is fully supported by Perforce. 
<b>This is now the recommended interface to use on Windows</b>.
There is no need to register any dlls. You can literally use xcopy deployment (or p4 sync :-). P4.Net uses inheritance, 
indexers and collection interfaces that all give it a more .Net-like interface 
than P4COM. Having said that, P4COM is still useful in situations where a COM interface is useful.</p>
<p>There is also an earlier (private by Shawn Hladky) version: <a href="http://public.perforce.com/guest/shawn_hladky/P4.Net/index.html">
P4.Net</a> - but this is not fully supported - see also
<a href="http://public.perforce.com/guest/shawn_hladky/P4.Net/index.html">P4.Net</a>
</p>
<h2>P4COM</h2>
 
<p>I presented a paper on an earlier version at the Perforce User Conference in 2001:
<a href="http://www.perforce.com/perforce/conf2001/index.html#myth">Adventures 
in API Land</a> for an overview of the API and how I use it. In particular pay 
attention to the section on error handling!</p>
 
<p>This DLL  is part of
<a href="http://www.perforce.com/perforce/products/plugins-ofc.html">P4OFC - the 
integration between Microsoft Office and Perforce</a> and well tested and stable 
in that environment!</p>
 
<h3 ALIGN="LEFT">Recent Changes</h3>
<p>In November 2014 P4COM was rebuilt using Visual Studio 2010 and the 2014.1 version of the P4API. 
It also uses the OpenSSL library which means it will now successfully talk to SSL enabled Perforce servers.
Because it uses a recent P4API it will handled files in streams depots.</p>
 
<h3 ALIGN="LEFT">Example Projects</h3>
<p ALIGN="LEFT">These are to be found in the zip file and in the test 
subdirectory in the Public Depot.</p>
 
<p ALIGN="LEFT">They demonstrate how to read and set environment values 
(p4.port, p4.client), and also how to perform a submit using a combination of 
&quot;p4 change -o&quot;, manipulate the results and then execute the command with &quot;p4 
submit -i&quot;</p>
 
<p ALIGN="LEFT">There are several example projects (very similar functionality):</p>
 
<ul>
  <li>
 
<p ALIGN="LEFT">VB6</p>
 
  </li>
  <li>
 
<p ALIGN="LEFT">VB.NET</p>
 
  </li>
  <li>
 
<p ALIGN="LEFT">C# (.NET)</p>
 
  </li>
  <li>
 
<p ALIGN="LEFT">Delphi 7 (very rudimentary at this point)</p>
 
  </li>
</ul>
 
<p ALIGN="LEFT">There is also:</p>
 
  <ul>
    <li>
 
<p ALIGN="LEFT">VBScript example (windows scripting)</p>
 
    </li>
</ul>
 
<p ALIGN="LEFT">Just load them up, compile and run and you should be fine 
(provided DLL was previously registered).</p>
 
<p ALIGN="LEFT">Note that Nick Levine has now made available a Lisp interface 
(with LispWorks) package which uses P4COM - see:</p>
 
<ul>
  <li>
 
<p ALIGN="LEFT"><a href="http://www.nicklevine.org/p4com/">
www.nicklevine.org/p4com/</a> </p>
 
  </li>
</ul>
 
<h2>Installation/Download</h2>
 
<p>You can download the complete source and a pre-built (release) version
<a href="http://public.perforce.com/guest/robert_cowham/perforce/API/p4com/main/src/releasemindependency/p4com.dll">of 
p4com.dll</a> from <a href="p4com.zip">p4com.zip</a> or from the src directory 
in the Perforce Public Repository (<a href="ftp://public.perforce.com/guest/robert_cowham/perforce/API/p4com/main/">browse 
via ftp</a>).</p>
<p>You will also need to download the following two (pre-built) files: 
<a href="http://public.perforce.com/guest/robert_cowham/openssl/1.0.1j/out32dll/libeay32.dll">libeay32.dll</a> and 
<a href="http://public.perforce.com/guest/robert_cowham/openssl/1.0.1j/out32dll/ssleay32.dll">ssleay32.dll</a> - 
install these as below before trying to register P4COM</p>
<p>To use it, you need to register the DLL (run regsvr32.exe on the DLL). I 
suggest you install in &quot;c:\program 
files\perforce&quot; or wherever you installed Perforce.</p>
<p>An installer will be provided in the future.</p>
 
<h2>Compiler</h2>
<p>This COM DLL has been built with Visual Studio 2010.</p>
<p>Use either of the project settings:</p>
<ul>
  <li>Debug</li>
  <li>Release Min Dependency</li>
</ul>
 
<p>To build P4COM, set up a Workspace with a View similar to the one below (note that the Perforce API and
the OpenSSL libraries are pulled in via View lines):</p>
<pre>
//guest/robert_cowham/perforce/API/p4com/main/src/... //p4com-test/p4com/src/...
//guest/robert_cowham/perforce/API/p4/p4api-2014.1.821990-vs2010_static/... //p4com-test/p4api/...
//guest/robert_cowham/openssl/1.0.1j/out32dll/libeay32.dll //p4com-test/p4com/src/ReleaseMinDependency/libeay32.dll
//guest/robert_cowham/openssl/1.0.1j/out32dll/ssleay32.dll //p4com-test/p4com/src/ReleaseMinDependency/ssleay32.dll
//guest/robert_cowham/openssl/1.0.1j/out32dll/libeay32.lib //p4com-test/openssl-lib/libeay32.lib
//guest/robert_cowham/openssl/1.0.1j/out32dll/ssleay32.lib //p4com-test/openssl-lib/ssleay32.lib
</pre>
 
 
<h2 ALIGN="LEFT">Main Interface</h2>
<p ALIGN="LEFT">The interface has been reworked from previous incarnations and 
is similar to that implemented by Tony Smith for Ruby.</p>
<p ALIGN="LEFT">There is a single object P4COM.p4 which should be 
instantiated and used.</p>
<p>Note that the command will pick up Perforce environment information in the 
the normal way - so global settings are used, or P4CONFIG settings are used. 
Make sure the current directory where your code is executing is set 
appropriately.</p>
<h2>Examples</h2>
<p>The simplest way to test is from VBScript. Note that since this can't access 
COM functions using String Arrays, it uses similar calls which take Variant 
Arrays.</p>
<pre>Test.vbs:
---------------
Option Explicit
 
Dim p4, arr, str, info, errs, warns
 
Set p4 = WScript.CreateObject(&quot;P4COM.p4&quot;)
 
p4.port = &quot;1666&quot;
p4.client = &quot;bruno_ws&quot;
p4.ExceptionLevel = 0
p4.connect
 
DisplayResult(&quot;info&quot;)
DisplayResult(&quot;describe 704&quot;)
 
p4.disconnect
p4.Tagged
p4.connect
DisplayResult(&quot;describe 704&quot;)
 
sub PrintArray(msg, arr)
    if (UBound(arr) >= 0) then
        WScript.Echo(msg & join(arr, chr(13) & chr(10)))
    end if
end sub
 
sub DisplayResult(cmd)
    WScript.Echo("Cmd: " & cmd)
    PrintArray "Info: ", p4.run_variant(cmd)
    PrintArray "Warnings: ", p4.Warnings_variant
    PrintArray "Errors: ", p4.Errors_variant
end sub
</pre>
 
<p>See other VBScript examples: <a href="test/test_parse.vbs">test\test_parse.vbs</a> 
and <a href="test/test_submit.vbs">test\test_submit.vbs</a>.</p>
<p>As an example of using it, in a VB project, make sure you have set a 
reference to COM object &quot;p4com 1.0 Type Library&quot;.</p>
<p>You can then execute a simple command such as &quot;p4 info&quot;:</p>
<pre>Dim p4 As P4COM.p4
Dim OutputArr() As String
Dim i as integer
 
p4.Connect
OutputArr = p4.run(&quot;info&quot;)
For i = LBound(OutputArr) To UBound(OutputArr)
    ResultBox.AddItem OutputArr(i)
Next
p4.Disconnect
</pre>
 
<p ALIGN="LEFT">This assumes a Listbox called ResultBox.</p>
 
<p ALIGN="LEFT">Something similar in C#:</p>
<pre>    P4COM.p4 m_p4 = new P4COM.p4();
    System.Array output;
    System.Array warnings;
    System.Array errors;
 
    m_p4.Connect();
    m_p4.ExceptionLevel = 1;
    try
    {
            output = m_p4.run(txtCmd.Text);
    }
    catch (System.Runtime.InteropServices.COMException ex)
    {
            MessageBox.Show(ex.Message);
    }
    DisplayResult();
 
    m_p4.Disconnect();
</pre>
 
<h3 ALIGN="LEFT">Using Forms</h3>
 
<p ALIGN="LEFT">It is also possible to do a Submit, getting and setting various 
parts of the submit form:</p>
 
<p ALIGN="LEFT">In C#:</p>
 
<pre>    public System.Windows.Forms.CheckedListBox Files;
    System.Array m_Files;
    m_p4.ParseForms();
    m_p4.Connect();
    output = m_p4.run("change -o");
    Description.Text = m_p4.get_Var("Description"); // Simple string variable
    m_Files = m_p4.get_ArrayVar("Files"); // StringArray variable
    Files.Items.Clear();
    for (i = m_Files.GetLowerBound(0); i <= m_Files.GetUpperBound(0); i++)
    {
        Files.Items.Add(m_Files.GetValue(i));
    }
</pre>
 
<p ALIGN="LEFT">The above gets values from the submit. Now we update having 
allowed the user to select files and type in a description, and finish 
the submit:</p>
 
<pre>    int i, count;
        
    m_p4.set_Var("Description", Description.Text); // Setting string var
    count = 0;
    for (i = 0; i < Files.Items.Count; i++)
    {
        if (Files.GetItemChecked(i))
        {
            count++;
        }
    }
    if (count > 0)
    {
        // There must be a better way of resetting m_Files than this
        // but I haven't found it yet!!
        string[] arr = new string[count];
        int j = 0;
        foreach(object item in Files.CheckedItems) 
        {
            arr[j++] = item.ToString();
        }
        m_Files = arr;	// Resets the array to new size
        m_p4.set_ArrayVar("Files", ref m_Files);
        output = m_p4.run("submit -i");
        errors = m_p4.Errors;
 
        string s = join(output);	// join output array together into one string
        s = s + "\n" + "Errors: " + join(errors);
        MessageBox.Show(s);
    }
</pre>
 
<h2>Unicode Enabled</h2>
<p>p4com.dll is unicode enabled and is an example of how to use the Perforce API 
with Unicode servers (where P4CHARSET is in use). Being COM, all strings such as 
filenames, change descriptions and the like, may be in Unicode and will be 
handled correctly - the challenge then is to be able to display the results!</p>
 
<h2>Interface</h2>
<h3>Properties</h3>
<p>The following properties may be read or updated. If you are updating them, 
then this must be done prior to calling Connect. If these properties are not 
set, then they default to system global settings (e.g. registry or environment, 
or P4CONFIG settings depending on the current directory).</p>
<ul>
  <li>Charset - equivalent of P4CHARSET</li>
  <li>Client - equivalent of P4CLIENT</li>
  <li>Cwd - Current working directory</li>
  <li>Host - Equivalent of P4HOST</li>
  <li>Language - Equivalent of P4LANGUAGE</li>
  <li>Os - Current operating system (read-only)</li>
  <li>Password - Equivalent of P4PASSWD</li>
  <li>Port - Equivalent of P4PORT</li>
  <li>User - Equivalent of P4USER</li>
</ul>
<h3>Running commands</h3>
<ul>
  <li>Connect - Connect to Perforce server - generates exception if fails.</li>
  <li>Disconnect - Disconnect from server</li>
	<li>Dropped - Has the connection dropped or not?<br>
&nbsp;</li>
  <li>run(cmd) - Returns the results of running the Perforce command as array of 
  strings (see example above)</li>
</ul>
<blockquote>
 
<p>cmd is a simple (valid) perforce command (with quotes around embedded spaces 
and without leading &quot;p4&quot;), such as:</p>
  <blockquote>
 
<p>info<br>
edit //depot/main/jam.c<br>
edit -t text+w &quot;//depot/some path with spaces/file.c&quot;<br>
clients</p>
  </blockquote>
</blockquote>
<ul>
  <li>run_variant - does the same as run but for VBScript or other environments 
	which require a variant to be returned</li>
	<li>Input - property to provide input, e.g. for setting password prior to 
	running login command.</li>
	<li>Errors - Returns array of any Errors that occurred during previous 'run'</li>
	<li>Errors_variant - same as Errors but for VBScript</li>
  <li>Warnings - Returns array of any Warnings that occurred during previous 
  'run'</li>
	<li>Warnings_variant - same as Warnings but for VBScript</li>
  <li>ExceptionLevel - Property to get and set this value: 0 means no 
  exceptions, 1 exception on errors only, 2 exceptions on warnings as well</li>
  <li>Tagged - Set's tagging of results like &quot;p4 -ztag&quot; global option</li>
  <li>ParseForms - Turns on Form parsing. Must be executed prior to Connect. 
  <b>This allows the use of Var and VarArray to get and set values. </b>Is only 
  relevant for commands which take the -o/-i flags such as p4 
  user/change/submit/jobspec/etc.</li>
  <li>TempFilename - Read-only property which is the name of any temporary file 
  produced by a p4 command such as 'print'</li>
  <li>Var(varName) - Get the value of the variable with the specified name 
  (requires ParseForms to have been set prior to Connect)</li>
  <li>VarExists(varName) - Does variable with specified name exist or not?</li>
  <li>ArrayVar(varName) - Get or set the array of values of the variable with 
  the specified name (requires ParseForms)</li>
  <li>ArrayVar_variant(varName) - Same as ArrayVar but returns variant for 
	VBScript etc</li>
	<li>FormatDateTime - Utility function for VB to format Unix date/time 
	seconds value as string using C Runtime Library call</li>
	<li>SetProg - set the program value which is reported in p4d server logs - 
	only takes effect after Connect</li>
	<li>SetVersion - set the program version which is reported in p4d server 
	logs - only takes effect after Connect</li>
	<li>SetTicketFile - set the ticket file to be used for subsequent Run() 
	commands</li>
	<li>SetProtocol - sets particular protocol values, e.g. &quot;api&quot;, &quot;57&quot; set to 
	use 2005.1 formatting.</li>
	<li>GetProtocol - read protocol values</li>
</ul>
 
<h3>Credits</h3>
<p>Thanks to Tony Smith who helped along the way, and whose
<a href="http://public.perforce.com/guest/tony_smith/perforce/API/Ruby/main/doc/index.html">
Ruby API</a> provided inspiration.</p>
 
<h3>Changes</h3>
<p>See <a href="CHANGELOG.txt">CHANGELOG.txt</a></p>
<p><a href="#top">Top</a>
</p>
<p>
$Id: //guest/perforce_software/p4office/main/p4com/index.html#1 $</p>
</body>
 
</html>

#	Change	User	Description	Committed
#1	11314	Robert Cowham	Initial population of perforce_software version of P4OFC	10 years ago
//guest/robert_cowham/perforce/API/p4com/main/index.html
#23	10878	Robert Cowham	Update doc and also .zip file.	10 years ago
#22	8062	Robert Cowham	Link to P4API.Net	13 years ago
#21	7460	Robert Cowham	Update with SetTicketFile	15 years ago
#20	7455	Robert Cowham	Update version of visual studio referenced	15 years ago
#19	6050	Robert Cowham	- Use P4API 2007.2 - Added SetProg, SetVersion, SetProtocol and GetProtocol	18 years ago
#18	5969	Robert Cowham	Add pointer to P4.Net	18 years ago
#17	5197	Robert Cowham	Updated to use 2005.1 P4API	19 years ago
#16	5195	Robert Cowham	Tidied	19 years ago
#15	5194	Robert Cowham	Changes (2005.1.0.0) Added Dropped() to detect dropped connections Added Input property t...	19 years ago
#14	4742	Robert Cowham	New version 2004.2.0.1 Added Scons for building zip file.	20 years ago
#13	4242	Robert Cowham	Fixed some String leaks. Fixed problem with writing to temporary files. Updated p4API to...	21 years ago
#12	4182	Robert Cowham	Release 1.0.0.4 - put output of Diff in normal output array.	21 years ago
#11	4156	Robert Cowham	Updated to support Variant Arrays (as required by VBScript).	21 years ago
#10	3880	Robert Cowham	Reference Nick's Lisp interface.	21 years ago
#9	3615	Robert Cowham	Tidied up	22 years ago
#8	3612	Robert Cowham	Version 1.0.0.2 New interface for ServerVersion. New put property ArrayVarVar which is th...	22 years ago
#7	3561	Robert Cowham	Renamed P4COMLib to P4COM and run from property to method.	22 years ago
#6	3546	Robert Cowham	Tidied up	22 years ago
#5	3545	Robert Cowham	More examples	22 years ago
#4	3544	Robert Cowham	Updated docs.	22 years ago
#3	3535	Robert Cowham	Update title	22 years ago
#2	3534	Robert Cowham	Added complete test projects for VB6, VB.NET and C#(.NET)	22 years ago
#1	3530	Robert Cowham	Docs and simple VB demo.	22 years ago