p4com is contributed by Robert Cowham of Vaccaperna Systems Ltd. Robert is a Perforce Consulting Partner and Trainer.
See the paper I presented at the Perforce User Conference in 2001: Adventures in API Land for an overview of the API and how I use it. In particular pay attention to the section on error handling!
This DLL is part of P4OFC - the integration between Microsoft Office and Perforce and thus stable.
These are to be found in the zip file and in the test subdirectory in the Public Depot.
They demonstrate how to read and set environment values (p4.port, p4.client), and also how to perform a submit using a combination of "p4 change -o", manipulate the results and then execute the command with "p4 submit -i"
There are 3 example projects (very similar functionality):
VB6
VB.NET
C# (.NET)
There is also:
VBScript example (windows scripting)
Just load them up, compile and run and you should be fine (provided DLL was previously registered).
Note that Nick Levine has now made available a Lisp interface (with LispWorks) package which uses P4COM - see:
You can download the complete source and a pre-built (release) version of the resulting DLL from p4com.zip or from the src directory in the Perforce Public Repository.
To use it, you need to register the DLL (run regsvr32.exe on the DLL). I suggest you install in "c:\program files\perforce" or wherever you installed Perforce.
An installer will be provided in the future.
This COM DLL has been built with MS VC++ 6.0 (SP5) and it also compiles happily with VC++ 7.0 (VS.NET).
Use either of the project settings:
The interface has been reworked from previous incarnations and is similar to that implemented by Tony Smith for Ruby.
There is a single object P4COM.p4 which should be instantiated and used.
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.
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.
Test.vbs:
---------------
Option Explicit
Dim p4, arr, str, info, errs, warns
Set p4 = WScript.CreateObject("P4COM.p4")
p4.port = "1666"
p4.client = "bruno_ws"
p4.ExceptionLevel = 0
p4.connect
DisplayResult("info")
DisplayResult("describe 704")
p4.disconnect
p4.Tagged
p4.connect
DisplayResult("describe 704")
sub DisplayResult(cmd)
WScript.Echo("Cmd: " & cmd)
info = p4.run_variant(cmd)
WScript.Echo("Info: " & join(info, chr(13) & chr(10)))
warns = p4.Warnings_variant
if (UBound(warns) >= 0) then
WScript.Echo("Warnings: " & join(warns, chr(13) & chr(10)))
end if
errs = p4.Errors_variant
if (UBound(errs) >= 0) then
WScript.Echo("Errors: " & join(errs, chr(13) & chr(10)))
end if
end sub
As an example of using it, in a VB project, make sure you have set a reference to COM object "p4com 1.0 Type Library".
You can then execute a simple command such as "p4 info":
Dim p4 As P4COM.p4
Dim OutputArr() As String
Dim i as integer
p4.Connect
OutputArr = p4.run("info")
For i = LBound(OutputArr) To UBound(OutputArr)
ResultBox.AddItem OutputArr(i)
Next
p4.Disconnect
This assumes a Listbox called ResultBox.
Something similar in C#:
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();
It is also possible to do a Submit, getting and setting various parts of the submit form:
In C#:
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));
}
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:
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);
}
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!
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).
cmd is a simple (valid) perforce command (with quotes around embedded spaces and without leading "p4"), such as:
info
edit //depot/main/jam.c
edit -t text+w "//depot/some path with spaces/file.c"
clients
Thanks to Tony Smith who helped along the way, and whose Ruby API provided inspiration.
2004-02-06 Returns the output of diff command in normal output array.
2004-01-28 Now able to be used from VBScript.
2003-11-07 Added reference to List usage of P4Com.
2003-09-02 Tidied up. Added ArrayVarVar put property to allow Variant arrays to be passed in (for Lisp compatibility!).
2003-08-08 Rename P4COMLib to P4COM and made run a method rather than property.