/*******************************************************************************
Copyright (c) 2001-2009, Perforce Software, Inc. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL PERFORCE SOFTWARE, INC. BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*******************************************************************************/
/*===================================================================\
| Name : P4ClientApi.H
|
| Author : Michael Bishop <mbishop@perforce.com>
|
| Description: Objective-C wrapper for the Perforce API.
\===================================================================*/
#import <CoreFoundation/CoreFoundation.h>
/*!
\interface P4ClientApi
\brief P4ClientApi is an Objective-C wrapper around the
<a href="http://www.perforce.com/perforce/doc.current/manuals/p4api/index.html">C++ ClientApi</a>.
This documentation is a supplement to the more complete Perforce C++ API documentation
available at: <a href="http://www.perforce.com/perforce/doc.current/manuals/p4api">http://www.perforce.com/perforce/doc.current/manuals/p4api</a>
\see <a href="http://kbmain.perforce.com/AllPerforceApplications/PerforceCApi">Perforce C++ Client API Knowledge Base Articles</a>.
\section OVERVIEW Overview
To retrieve data from a Perforce server you must complete three tasks:
-# Establish a connection
-# Run one (or more) commands
-# Disconnect
In addition to those tasks, there are a list of properties you may
set on the api instance to affect its operation.
\section SCHEDULING_ISSUES Scheduling Issues
The Perforce C++ API is a blocking API; that is, when a method is
executed to connect to, or retrieve data from the server, that method
does not return until the data has been sent and the command is finished.
This is usually unacceptable in a graphical user environment.
The Mac's solution to this is to create a network request and add it as
a source to the current RunLoop. The core Perforce C++ API has not been
written to support this mechanism directly. Instead you must execute the
client api requests in a separate thread so the current thread does not
block and send the results back to the originating thread.
Typically, this involves a lot of work to package mesages so they can be
sent across threads. Much care has been taken to handle as much of this
for you as possible. You are still responsible for scheduling the client
api request in a separate thread (to retain the most scheduling control)
but you can specify the thread to which the server results will be sent
and the return messages will be packaged up and sent to your delegate
in that thread.
Convenience methods to create NSInvocation objects for key client api
methods are provided for your use. You can add these invocations to an
NSOperationQueue and let the system schedule them, or you can ask the
invocation object itself to execute in another thread using NSObject's
<tt>performSelectorInBackground:withObject:</tt> (and variants).
Below is an example of blocking, and non-blocking ways of connecting to
the server:
BLOCKING:
\code
P4ClientApi * api = [[[P4ClientApi alloc] init] autorelease];
NSError * e;
// Your thread could block for a while if the server is not running
if (![api connectToPort:@"perforce:1666" withProtocol:nil error:&e] )
return e;
... run the command
\endcode
NON-BLOCKING:
\code
P4ClientApi * api = [[P4ClientApi alloc] init];
// Instead, of calling the method directly, create an invocation to be
// executed in another thread
api.callbackThread = [NSThread currentThread];
NSInvocation * invocation = [api invocationForConnectToPort:@"perforce:1666"
protocol:nil
delegate:self];
NSInvocationOperation * operation = [[NSInvocationOperation alloc] initWithInvocation:invocation];
// the operation queue will schedule the operation in another thread and return immediately
[operationQueue addOperation:operation];
[operation release];
...
-(void)clientApi:(P4ClientApi *) api
didFailToConnectWithError:(NSError*)s
{
NSLog(@"failed to connect to %@", api.p4port);
[api release];
}
-(void)clientApiDidConnect:(P4ClientApi*)api
{
... run the command on the client api
}
\endcode
\section HANDLING_ERRORS Error Handling
The Perforce Objective-C API wraps up native Perforce errors into an NSError
object. It does so in the following manner:
-# The domain of the NSError is set to: \p P4ErrorDomain.
-# The formatted message from the C++ Error object is passed in the NSError
object as the \p localizedDescription.
-# The code of the first ErrorId in the C++ Error is placed into the NSError \p code.
You can use this to compare with the included ErrorId instances in the C++ header files.
-# Additionally, you can see the pieces of the above ErrorId by looking in the userInfo field of
the NSError and finding the NSValues for these keys:
P4SubsystemErrorKey, P4SubCodeErrorKey, P4SeverityErrorKey, P4GenericErrorKey
*/
/// \mainpage P4ClientApi
/// \copydoc P4ClientApi
#import <Foundation/Foundation.h>
/// \brief establishes the NSError domain for Perforce client errors
extern NSString * const P4ErrorDomain;
/// \brief Key to retrieve the subsystem code of an Error from Perforce
extern NSString * const P4SubsystemErrorKey;
/// \brief Key to retrieve the code (within a subsystem) of an Error from Perforce
extern NSString * const P4SubCodeErrorKey;
/// \brief Key to retrieve the severity of an error from Perforce
extern NSString * const P4SeverityErrorKey;
/// \brief Key to retrieve the generic code of an Error from Perforce
extern NSString * const P4GenericErrorKey;
/// \brief Used to notify the server of the protocol level the client
/// understands
/// \see <a href="http://kb.perforce.com/P4dServerReference/ProtocolLevels/PerforceClientLevels">Perforce Protocol Levels</a>
extern NSString * const P4ProtocolVersion;
@protocol P4ClientApiConnectionDelegate;
@protocol P4ClientApiCommandDelegate;
@interface P4ClientApi : NSObject {
@private
void * _clientApi; // untyped to prevent C++ header inclusion
void * _currentClientUser; // untyped to prevent C++ header inclusion
NSString * _currentCommand;
NSArray * _currentArgs;
id _userInfo;
NSThread * _callbackThread;
BOOL _connected;
NSString * _ticketFilePath;
NSString * _programIdentifier;
NSString * _version;
NSDictionary * _requestedProtocol;
BOOL _prefersTaggedOutput;
int _rowScanningLimit;
int _tableLockingTimeLimit;
int _returnedResultsLimit;
}
/*! \name Connecting
Use these to establish a connection to the server.
*/
//@{
/*!
\brief Establish a connection and prepare to run commands.
Use this method to establish a connection to a Perforce server. It must be
made before running any commands with runCommand:withArguments:delegate:
The protocol is an NSDictionary of keys and values. The values can be of these types
NSString, NSNumber, NSNull. They will all be converted to strings when
sent to the server.
\note This method does not return until after a connection is made or unsuccessful.
For unsucessful connections, this could last 5 seconds, blocking your
event-loop. You may wish to instead call
connectToPort:withProtocol:delegate: in another thread and
have it return messages to your current thread.
\param port a P4PORT value or \p nil to use the default.
\param requestedProtocol A dictionary of protocol values to configure the connection.
You may pass \p nil if you don't have a specific protocol
requirement.
\param error a pointer to an NSError pointer or \p nil
(see \ref HANDLING_ERRORS)
\result YES if the connection was completed
\result NO if the connection could not be made. An error will be returned in
\p which the caller must retain.
\note Internally, this is equivalent to calling
<tt>ClientApi::SetPort();
ClientApi::SetProtocol();
ClientApi::Init();</tt>
\see connectToPort:withProtocol:delegate:
\see ClientApi::SetPort()
\see ClientApi::SetProtocol()
\see ClientApi::Init()
*/
-(BOOL)connectToPort:(NSString*)port
withProtocol:(NSDictionary*)requestedProtocol
error:(NSError **)error;
/*!
\brief Establish a connection and prepare to run commands.
Use this method to establish a connection to a Perforce server. It must be
made before running any commands with runCommand:withArguments:delegate:
The protocol is an NSDictionary of keys and values. The values can be of these types
NSString, NSNumber, NSNull. They will all be converted to strings when
sent to the server.
\note This method does not return until after a connection is made or unsuccessful.
For unsucessful connections, this could last 5 seconds, blocking your
event-loop. You may wish to instead call it in another thread and
have it return messages in your current thread to your delegate.
\param port a P4PORT value or \p nil to use the default.
\param requestedProtocol A dictionary of protocol values to configure the connection.
You may pass \p nil if you don't have a specific protocol
requirement.
\param delegate a delegate object that is used to process messages from the server.
It is not retained.
\note Internally, this is equivalent to calling
<tt>ClientApi::SetPort();
ClientApi::SetProtocol();
ClientApi::Init();</tt>
\see connectToPort:withProtocol:error:
\see ClientApi::SetPort()
\see ClientApi::SetProtocol()
\see ClientApi::Init()
*/
-(void)connectToPort:(NSString*)port
withProtocol:(NSDictionary*)requestedProtocol
delegate:(id<P4ClientApiConnectionDelegate>)delegate;
/*! \brief Convenience method to create an invocation for use in non-blocking calls.
Use this method to create an NSInvocation that can be called in another
thread or added to an NSOperationQueue as an NSInvocationOperation.
The protocol is an NSDictionary of keys and values. The values can be of these types
NSString, NSNumber, NSNull. They will all be converted to strings when
sent to the server.
\note as is consistent with NSInvocations, the arguments are not
retained by default. Creating an NSInvocationOperation will retain
the arguments automatically.
\param port a P4PORT value or \p nil to use the default.
\param requestedProtocol A dictionary of protocol values to configure the connection.
You may pass \p nil if you don't have a specific protocol
requirement.
\param delegate a delegate object that is used to process messages from the server.
\see connectToPort:withProtocol:delegate:
*/
-(NSInvocation*)invocationForConnectToPort:(NSString*)port
withProtocol:(NSDictionary*)requestedProtocol
delegate:(id<P4ClientApiConnectionDelegate>)delegate;
// @}
/*! \brief The port connected to in connectToPort:withProtocol:error:
\note It could be a Bonjour name.
\see ClientApi::GetPort()
*/
@property(readonly, copy) NSString * p4port;
/*! \brief The current user name.
\see ClientApi::Set/GetUser()
*/
@property(readwrite, copy) NSString * user;
/*! \brief The current client name.
\see ClientApi::Set/GetClient()
*/
@property(readwrite, copy) NSString * client;
/*! \brief The name of the character set used for translation between
the server and the client.
This is required field when talking to a server in unicode mode and required to be
\p nil when communicating with a non-unicode server. Perforce recommends
the value of \p utf8 with Mac OS X-based clients.
For more information on using the P4API with unicode-enabled servers, see
<a href="http://kbmain.perforce.com/P4dServerReference/Internationalization/UnicodeAndP4..sAndAnswers">Unicode and P4API</a>
\note This calls ClientApi::SetTrans() before establishing a connection
*/
@property(readwrite, copy) NSString * charset;
/*! \brief The current working directory.
\see ClientApi::Set/GetCwd()
*/
@property(readwrite, copy) NSString * currentWorkingDirectory;
/*! \brief The password sent to the server for this connection.
\see ClientApi::Set/GetPassword()
*/
@property(readwrite, copy) NSString * password;
/*! \brief Indicates to the server that the client prefers data to be returned via
the clientApi:didReceiveTaggedResponse: method of the command delegate.
This is \p YES by default.
*/
@property(readwrite, assign) BOOL prefersTaggedOutput;
/*! \brief The name of this host. Unless set explicitly may not be available until
after connecting to the server.
\see ClientApi::Set/GetHost()
*/
@property(readwrite, copy) NSString * hostname;
/*! \brief The location of the user's ticketfile
\note This must be the full path to the file and not a directory.
\see ClientApi::Set/GetTicketFile()
*/
@property(readwrite, copy) NSString * ticketFilePath;
/*! \brief The identifier of the application program which will show up in
logging viewed with the <tt>p4 monitor</tt> command and in
server log output.
It's "P4V" below.
\code
45381 P4V/v60 10.0.105.2194 R joeuser joeuser 04:01:53 IDLE none
\endcode
\note Unlike the C++ API, you can set this at anytime.
\see ClientApi::Set/GetProg()
*/
@property(readwrite, copy) NSString * programIdentifier;
/*! \brief The version of the application program which will show up in
logging viewed with the <tt>p4 monitor</tt> command and in
server log output.
When not set, it defaults to the protocol level of the Client API libraries.
It's "v60" below.
\code
45381 P4V/v60 10.0.105.2194 R joeuser joeuser 04:01:53 IDLE none
\endcode
\note Unlike the C++ API, you can set this at anytime.
\see ClientApi::Set/GetProg()
*/
@property(readwrite, copy) NSString * version;
/*! \brief The userInfo object set on the api object as context when connecting
or running commands.
\see runCommand:withArguments:delegate:
*/
@property(readwrite, retain) id userInfo;
/*! \brief The thread in which the client api will send back its responses.
This is useful when executing the client api in another thread
and sending back responses to the main thread for asynchronous
operation.
When the value is \p nil, the api object will call back to whatever
the currently executing thread is.
It's \p nil by default
*/
@property(readwrite, retain) NSThread * callbackThread;
/*! \brief The filename used when Perforce searches for configuration files
from which to retrieve default values.
\see ClientApi::GetConfig()
*/
@property(readonly) NSString * configurationFilename;
/*! \brief The state of the connection. If the connection was dropped or
otherwise disconnected, this will return NO.
\see ClientApi::Dropped()
*/
@property(readonly) BOOL connected;
/*! \name Executing commands
Once you have established a connection to the server,
you can use these to execute commands.
*/
//@{
/*! \brief Executes a command on the Perforce server.
Use this method to actually execute a command on the Perforce server.
Results are returned via the delegate.
\note This method does not return until after after the server has completely processed
the command and has sent clientApiDidFinishCommand: to your delegate. Because
this stops the current RunLoop from continuing, you may find it desirable
to make this call in another thread and have the server send messages back
to the current thread, allowing the RunLoop to continue.
\note Before making thing call, you must have a connection established through
connectToPort:withProtocol:error:
\attention This method is not thread-safe. If you are scheduling this
call by scheduling invocation objects, you must make sure
that this call returns before the next invocation is called.
You can do this by creating a separate NSOperationQueue per
client api instance and making sure the queue's
<tt>maxConcurrentOperationCount</tt> equals 1
before queuing your invocation objects in it.
\param command the command you want to run (eg: "sync").
\param args An array of arguments to be sent with the command. You may pass \p nil if the
\p command doesn't require arguments to execute.
\param variables a set of protocol variables that are valid only for this command
\param delegate a delegate object that is used to process messages from the server.
It is not retained.
\note Internally, this is equivalent to calling
<tt>ClientApi::SetArgs();
ClientApi::RunCmd();</tt>
*/
-(void)runCommand:(NSString *)function
withArguments:(NSArray*)args
commandVariables:(NSDictionary*)variables
delegate:(id<P4ClientApiCommandDelegate>)delegate;
-(void)runCommand:(NSString *)function
withArguments:(NSArray*)args
delegate:(id<P4ClientApiCommandDelegate>)delegate;
/*! \brief Convenience method to create an invocation for use in non-blocking calls.
Use this method to create an NSInvocation that can be called in another
thread or added to an NSOperationQueue as an NSInvocationOperation.
\note as is consistent with NSInvocations, the arguments are not
retained by default. Creating an NSInvocationOperation will retain
the arguments automatically.
\param command the command you want to run (eg: "sync").
\param args An array of arguments to be sent with the command. You may pass \p nil if the
\p command doesn't require arguments to execute.
\param delegate a delegate object that is used to process messages from the server.
\see runCommand:withArguments:delegate:
*/
-(NSInvocation*)invocationForRunCommand:(NSString *)command
withArguments:(NSArray*)args
delegate:(id<P4ClientApiCommandDelegate>)delegate;
//@}
/*! \name Advanced Performance Options
Use these to control or limit server calculation or output.
*/
//@{
/*! \brief Limits the rows of data considered and prevents the server from
making large-scale scans.
Assigning a value of 0 (the default) has no effect.
\see http://kb.perforce.com/AdminTasks/PerformanceTuning/MaximizingPe..Performance
\see p4 help maxscanrows
*/
@property(readwrite, assign) int rowScanningLimit;
/*! \brief Limits the amount of time spent during data scans to prevent the
server from locking tables for too long.
Assigning a value of 0 (the default) has no effect.
\see http://kb.perforce.com/AdminTasks/PerformanceTuning/MaximizingPe..Performance
\see p4 help maxlocktime
*/
@property(readwrite, assign) int tableLockingTimeLimit;
/*! \brief Limits the rows of resulting data buffered and prevents the server
from using excessive memory.
Assigning a value of 0 (the default) has no effect.
\see http://kb.perforce.com/AdminTasks/PerformanceTuning/MaximizingPe..Performance
\see p4 help maxresults
*/
@property(readwrite, assign) int returnedResultsLimit;
//@}
/*! \name While running commands...
In your P4ClientApiCommandDelegate methods, you can call these
to retrieve the items passed to <tt>runCommand:withArguments:delegate:</tt>...
*/
//@{
/*! \brief The command that the client api instance is executing.
\see runCommand:withArguments:delegate:
*/
@property(readonly, copy) NSString * currentCommand;
/*! \brief The arguments for the currently executing command.
\see runCommand:withArguments:delegate:
*/
@property(readonly, copy) NSArray * currentArguments;
//@}
/*! \name Disconnecting
These terminate your connection to the server, reporting
any residual errors.
*/
//@{
/*! \brief Disconnects from the server and reports disconnection errors.
\param error a pointer to an NSError or \p nil
(see \ref HANDLING_ERRORS)
\result YES if an error was raised
\result NO if the disconnection has no errors.
\see ClientApi::Final()
*/
-(BOOL)disconnect:(NSError **)error;
/*! \brief Disconnects from the server and reports disconnection errors.
\param delegate a delegate object that is used to process messages from the server.
It is not retained.
\see ClientApi::Final()
*/
-(void)disconnectWithDelegate:(id<P4ClientApiConnectionDelegate>)delegate;
/*! \brief Convenience method to create an invocation for use in non-blocking calls.
Use this method to create an NSInvocation that can be called in another
thread or added to an NSOperationQueue as an NSInvocationOperation.
\note as is consistent with NSInvocations, the arguments are not
retained by default. Creating an NSInvocationOperation will retain
the arguments automatically.
\param delegate a delegate object that is used to process messages from the server.
\see disconnectWithDelegate:
*/
-(NSInvocation*)invocationForDisconnectWithDelegate:(id<P4ClientApiConnectionDelegate>)delegate;
//@}
/*! \name Setting and inspecting the server protocol
You can request specific protocol parameters when calling
connectToPort:withProtocol:error:. After running
a command, the server will also send back additional parameters
about the connection.
*/
//@{
/*!
\brief The protocol dictionary passed in to connectToPort:withProtocol:...
\see connectToPort:withProtocol:error:
*/
@property(readonly, copy) NSDictionary * requestedProtocol;
/*!
\brief The protocol parameters (as a property) containing information about
communication between the server and client.
After making a call to runCommand:withArguments:delegate:,
the server sends a dictionary of additional protocol variables back to the
client with additional information about the communication between server
and client.
\note This is \b different from the dictionary passed in to connectToPort:withProtocol:error:
\see ClientApi::GetProtocol()
*/
-(NSObject*)serverProtocolValueForKey:(NSString*)key;
//@}
@end
/*!
\protocol P4ClientApiConnectionDelegate
\brief Implement this in a delegate when establishing a non-blocking
connection to a Perforce server.
connectToPort:withProtocol:error: is a blocking
call that will not return until a connection is made, or fails. The
timeout is roughly 5 seconds. For this reason, you are encouraged to
implement this protocol and make your connection in another thread.
*/
@protocol P4ClientApiConnectionDelegate <NSObject>
@optional
/*!
\brief Called on your delegate when the client has sucessfully
established a connection. You may now start running
commands with
runCommand:withArguments:delegate:
\param api the client api instance calling this method.
*/
-(void)clientApiDidConnect:(P4ClientApi*)api;
/*!
\brief Called on your delegate when the client was not able to establish
a connection. The client may wait for about 5 seconds before
it calls your delegate with this method.
\param api the client api instance calling this method.
\param error the error message which you can report to the user.
(see \ref HANDLING_ERRORS)
*/
-(void)clientApi:(P4ClientApi*)api didFailToConnectWithError:(NSError*)error;
/*!
\brief Called on your delegate when the client disconnects from the
server (by calling disconnectWithDelegate:).
\param api the client api instance calling this method.
\param error the residual errors from the server
(see \ref HANDLING_ERRORS)
*/
-(void)clientApi:(P4ClientApi*)api didDisconnectWithError:(NSError *)error;
@end
/*!
\protocol P4ClientApiCommandDelegate
\brief Implement this to receieve messages from the Perforce server as a
result of calling
runCommand:withArguments:delegate: on a
P4ClientApi instance.
Each method returns a different type of response
depending on the executing command and the configuration of the
P4ClientApi instance. It is closest to the ClientUser class in the C++ API.
\note If a message is not implemented by your delegate class, the
ClientUser behavior is executed by default. That behavior is what
the p4 command-line CLI uses.
Each of of these methods has an analagous callback in the C++ API. They
are documented with each method.
*/
@protocol P4ClientApiCommandDelegate <NSObject>
@optional
/*!
\brief Called on your delegate when the client was not able to establish
a connection. The client may wait for about 5 seconds before
it calls your delegate with this method.
\param api the client api instance calling this method.
\param error the error message which you can report to user.
(see \ref HANDLING_ERRORS)
\see ClientUser::OutputError
*/
-(void)clientApi:(P4ClientApi*)api didReceiveError:(NSError*)error;
/*!
\brief Called on your delegate by the server during most Perforce
commands; its most common use is to display listings of information
about files.
\note The messages from the server in this call are "simple" because
they are meant to be sent directly to the console and do not
include a code for the message.
\param api the client api instance calling this method.
\param message the printable message from the server
\param level the indentation "level" of the output
\see ClientUser::OutputInfo(
*/
-(void)clientApi:(P4ClientApi*)api didReceiveSimpleServerMessage:(NSString*)message level:(char)level;
/*!
\brief Called on your delegate when the server has formatted output.
This is much more useful than a simple message. Normally, only the results
of an "fstat" command come through this method, but you can get many more
commands to output in this way, by setting \p prefersTaggedOutput to
YES on the P4ClientApi instance.
\code
api.prefersTaggedOutput = YES;
\endcode
\param api the client api instance calling this method.
\param response the dictionary containin a structured response.
\see ClientUser::OutputStat
*/
-(void)clientApi:(P4ClientApi*)api didReceiveTaggedResponse:(NSDictionary*)response;
/*!
\brief Called on your delegate typically as a result of a "print" command
on a binary file.
\param api the client api instance calling this method.
\param data the binary data from the server
\see ClientUser::OutputBinary
*/
-(void)clientApi:(P4ClientApi*)api didReceiveBinaryContent:(NSData*)data;
/*!
\brief Called on your delegate typically as a result of a "print" command
on a text file.
\param api the client api instance calling this method.
\param text the text data from the server
\see ClientUser::OutputText(
*/
-(void)clientApi:(P4ClientApi*)api didReceiveTextContent:(NSString*)text;
-(void)clientApi:(P4ClientApi*)api didRequestInputAsText:(NSString**)text;
/*!
\brief Called on your delegate when the server has finished processing a
command.
\param api the client api instance calling this method.
\see ClientUser::Finished()
*/
-(void)clientApiDidFinishCommand:(P4ClientApi*)api;
@end
| # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #1 | 8331 | Matt Attaway |
Adding initial version of MacMenu for Perforce MacMenu is a helpful Perforce client that sits in your toolbar. It allows you to run standard Perforce operations on the document that is open the currently active editor/viewer. |