You can link to Perforce depot information from within your own HTML documents by constructing URLs that direct P4Web to return specified data. Such URLs can be used in email, in web pages (static or CGI-generated), and in any context where URLs are useful. You can create scripts that construct such URLs and pass them to a Web browser, enabling users to display Perforce information without requiring them to install Perforce client applications on their computer. In constructing the URLs, use the same options and flags that you use on the command line.

Some simple examples:

Display the file //depot/main/atlas/readme.txt http://myp4web:8080/depot/main/atlas/readme.txt
List the files in //depot/main/atlas http://myp4web:8080/depot/main/atlas/
Display the depot root for the server to which P4Web is connected http://myp4web:8080/
List the executable files (files with a .exe extension) in a specified folder http://myp4web:8080//depot/main/binaries/windows/*.exe
Display a file as it appeared on a specified date http://myp4web:8080//depot/www/sitemap.html@2004/1/1

URL Syntax

The syntax for P4Web URLs is as follows:

http://p4webhostname:port/[@parameters@][/]/object[[?ac=n][&parameters]]

P4Web uses a variety of other elements in the URLs that it constructs, but you can omit these elements in the URLs that you construct for your queries. The basic elements of URLs for P4Web are as follows.

Element

Description

http://p4webhostname:port/ The P4Web server and port
parameters

A list of arg=value pairs separated by “&”: arg=value[&arg=value]

Parameters can be specified before or after the object. If you specify parameters before the object, delimit the parameters with "at" signs (@). If you specify parameters after the object, precede the list of parameters with a question mark (?). The parameter syntax is the standard format for URL queries.

object Depot file, spec name (for example, job, user, label, etc.), or a P4 command. If you omit the action code, the object is interpreted as a depot path specifying a file or folder. The parameter list can include an action code.
ac=n (optional) Action code, preceded by "?" (that is, formatted as GET data). Specify the action code in the list of parameters as described above.

To specify a folder or file that resides in the Perforce server, use the following syntax:

//depot_path/[@revision_specifier]

where //depot_path/ specifies the file or folder and revision_specifier is a changelist number, label, or date in yyyy/mm/dd format. The depot path can be preceded by a single slash or the Perforce standard double slash.

To specify special-purpose characters in URLs, use the standard escape sequence %hex-value. You must escape the following special-purpose characters:

For example, to display a list of labels owned by user bruno, you can create a URL that includes the p4 labels command. The following URL uses the %20 escape sequence to specify the spaces required to separate the syntactic elements of the command:

http://myserver.perforce.com/p4%20labels%20-u%20bruno?ac=201

Action Codes

The following table lists the action codes that are supported for P4Web URLs. There are no action codes for commands that require administrator privileges.

Type

Description

Action
Code

Branches

Display view for a specified branch specification

Example: http://myp4web:8080/talkhouse1.0?ac=14

14

Compare branched source and target files using a branch specification

Example: http://myp4web:8080/talkhouse1.0?ac=126

126

List branch specifications

Example: http://myp4web:8080/?ac=82

82
Changelists

Display detail for specified changelist

Example: http://myp4web:8080/799?ac=10

 

10

List all submitted changelists for specified path

Example: http://myp4web:8080//depot/Talkhouse/rel1.0/?ac=43

43

Display fixes for a specified changelist

Example: http://myp4web:8080/799?ac=133

133

Display submitted changelists containing specified file

Example: http://myp4web:8080//depot/Jam/MAIN/src/Build.com?ac=69

69
Diffing

Diff two file revisions

Example: http://myp4web:8080//depot/main-dev/EBolt.java?ac=19&rev1=1&rev2=2

or:

http://myp4web:8080/@rev1=1&rev2=2@//depot/main-dev/EBolt.java?ac=19

19
Files

List files in specified path matching specified pattern (including wildcards)

Example: http://myp4web:8080/@pat=*.java@//depot/Talkhouse/main-dev/?ac=30

30

Display file as plain text within an HTML document

Example: http://myp4web:8080//depot/www/dev/index.html?ac=64

64

Send file contents to browser as text/plain document

Example: http://myp4web:8080//depot/www/dev/index.html?ac=18

18

Display annotated file text

Example: http://myp4web:8080//depot/www/dev/index.html?ac=193

193

Display revision history

Example: http://myp4web:8080//depot/main/ProjectX/Help/roadmap.html?ac=22

22

Diff a file revision against the previous revision

Example: http://myp4web:8080//depot/main-dev/EBolt.java?ac=185&rev1=9

185
Jobs

Display a list of files and folders in specified path

Example: http://myp4web:8080//depot/www/dev/?ac=83

83

List jobs

Example: http://myp4web:8080//?ac=107

107

Display job detail

Example: http://myp4web:8080/job000018?ac=111

111

Display changelists that fix a specified job

Example: http://myp4web:8080/job000018?ac=135

135

Display the job specification

Example: http://myp4web:8080/?ac=130

130
Labels

List files in a specified label

Example: http://myp4web:8080/jam-1.1.0?ac=118

118

List labels

Example: http://myp4web:8080//?ac=77

77

Display detail for a specified label

Example: http://myp4web:8080/jam-1.1.0?ac=16

16

List labels that contain files in a specified path

Example: http://myp4web:8080//depot/www/dev/?ac=127

127

(or use 184 to omit links)

Reporting

Display file view of server positioned as specified (to //depot, in this example).

Example: http://myp4web:8080//depot/?ac=71

71

Show status of specified file (same as ac=22 minus revision history)

Example: http://myp4web:8080//depot/Jam/MAIN/src/Build.com?ac=104

104

List all open files (all workspaces). Be advised that this action code can return extremely large amounts of output.

Example: http://myp4web:8080//?ac=62

62

Run a p4 command, returning output as XML.

Example: http://myhost:8080//p4%20info?ac=201

201

Display server and P4Web version info

Example: http://myp4web:8080//?ac=151

151
Users

Display details for specified user

Example: http://myp4web:8080/bruno?ac=17

17

List users

Example: http://myp4web:8080//?ac=81

81

Commonly-Used Parameters

P4Web uses a variety of parameters in the URLs it constructs. Many of the parameters are for internal use and are not relevant for scripting. To construct the precise URL for the information you seek, browse using P4Web until you have the desired results displayed, then copy the URL from the address bar and use it as the basis to construct your own URL. Commonly-used parameters are as follows.

Parameter

Description

&cd=path Path to a folder
&nx=n Maximum number of items to display
&pat=file_matching_pattern Wildcard expression for matching a set of files
&rev1=n, @rev2=n Specifies a pair of revisions, for example, for diffing files
&sho=flag Specifies the partial results that you want returned, as described below
&sr=@revision_specifier A Perforce revision specifier (revision number, label, date, or changelist number)

Displaying Sections of Results Pages

To display specified sections of the full-page results that P4Web normally returns, add sho=section[, section...] parameters to the URL.

Example: sho=title,filter,body. This feature enables you to embed specified portions of P4Web pages into your own web pages.

Valid sections are as follows:

Description
Keyword
Remark
Perforce logo
logo
 
Header
header
Includes logo
Path
path
Includes logo and header
Tabs
tabs
 
Toolbar
toolbar
 
Title
title
 
Filter
filter
 
Body
body
(Required)
Copyright
copyright
 

To ensure that any generated links in results pages return the same sections, place the sho parameter between the "at" signs (@) in the URL that you send to P4Web. For example:

http://p4webhost:8080/@sho=logo,body@//?ac=83

The page returned by the preceding URL contains only the logo and body. All generated links in this results page also contain the sho=logo,body parameter and return only the logo and body when you click them. To ensure that all generated links in the results page return full pages, place the sho parameter at the end of the URL.