User contributed content on the Perforce Public Depot is not supported by Perforce,
although it may be supported by its author. This applies to all contributions 
even those submitted by Perforce employees.

P4NodeApi is an example node extension supporting calls to the Perforce C++ API.
It has been tested with node v0.8.7

Installation:

1. Download the Perforce C++ API library and files from : http://www.perforce.com/product/components/apis

2. For node < v0.8, edit the wscript file in this project to the location of the API libraries.
   For node >= v0.8, edit the bindings.gyp file in this project to the location of the API libraries

3. For node >= v0.8, install node-gyp:
      sudo npm install -g node-gyp

4. Make sure your environmental variables (P4PORT, P4USER, P4CLIENT) are set to a running server
    that you wish to test against.

5. Execute 'runit' from this directory to build the plugin and run 'test.js'.

Usage (see 'test.js' & 'test4.js' for examples):

1. Get a reference to the object constructor.
        (eg: 'var P4NodeApi = require("./build/Release/perforce_nodeapi").PerforceNodeApi;')

2. Use the constructor to create a new connection object.
    
    2a. If you pass the constructor nothing, it will use the env vars or values names in P4CONFIG - as any p4client would use. 
    
    2b. Alternatively, you can pass the constructor an object to specify the port, user, and/or client.
        Unspecified parameters default to the P4 environment variables.
                var p4 = new P4NodeApi({
                    'port':  'perforce:1666',
                    'client':  'aclient',
                    'user':  'thisisyou',
                    'password':     'mypassword',
                    'json':     'false',   # output string format = defaults to true ..false -> p4 default output
                });
    
3. Use the connection object's run (and only) method (har-har-har) to send a command to the server.

    3a. The first parameter is an array containing the command and any arguments. The first value
            in the array is the command string, and any additional values are used as arguments.
            
        Note: this must be an array, even if it only contains one string.
        
    3b. The second parameter can be a string if you are running a command with a "-i" argument and
            need to set a string to be the input. For non-"-i" commands this parameter is not needed,
            so it can be any string, or it can be omitted.
            
    3c. The third (or second if no input string is passed) parameter is the callback function. When the
            server responds, this function will be called. It will be passed two values: 
                - The first is any error messages (or null if there are none).
                - The second is the (non-error) response data.
        
    Note: Each "new P4NodeApi" object can only really run one command concurrently. Successive runs from the
            same object are totally safe. (Just make sure you know it's actually done running!)
          For concurrent runs, use a wrapper that will create a new 'cloned' object per command it is to run,
            and then destroy that upon completion.