Feedback
Table Of Contents
Methods for Controlling Video Operations
Methods for Obtaining Information about the AxClient or Video Streams
Methods for Creating Clips and Snapshots
Methods for Controlling VMR Display
Methods for Setting up Callbacks
AxClient API Methods
This chapter lists the methods in the AxClient API, provides detailed information about each method. provides examples for using the methods. It includes the following topics:
•
Methods for Controlling Video Operations
•
•
•
•
Methods for Controlling Video Operations
The following sections describe the methods that provide functionality for controlling a video feed.
mtStartStream
HRESULT mtStartStream (
String source,
int version,
bool isProxy);Purpose
Loads the designated live or archived video stream into the AxClient and starts playing the stream.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
onStartOfStream, onMtStartStreamDone.
Notes
This method is equivalent to calling both switchTo() and playForward() in previous versions of the API. Therefore, playForward() does not need to be called after mtStartStream() is invoked.
This call does not immediately return success or failure: instead, the mtStartStreamDone and onStartofStream events must be caught. Only once both events are caught can the application be certain a stream is playing. If only the mtStartStreamDone event is caught (and no onStartofStream fires) then the client finished with the mtStartStream call, but the server did not return a stream to play.
Examples
C# Example
// Wrap the AxClient with AXImp and include the wrapped ActiveX dll in your projecttry {this.axc.mtStartStream(bwims://1.1.1.1/p_s1_CiscoHDCamera_1, 6, true);}catch(Exception ex) {this.logger.subLog("Exception in mtStartStream - " + ex.Message);}JavaScript example
/* Embed the AxClient as an object, and then use this syntax where the embedded object ID is IMC1. */var axc = document.applets["IMC1"];axc.mtStartStream(bwims://1.1.1.1/p_s1_CiscoHDCamera_1, 6, true);Related methods
mtStreamStarting
HRESULT mtStreamStarting (VARIANT_BOOL *pVal);
Purpose
Returns the status of the video stream started by the mtStartStream method.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
onStartOfStream.
Notes
This API method is useful in situations where certain functionality must be performed only after a stream has started.This approach requires the client to perform work to return the state information, however, and does not work well when thread blocking occurs. For example, in the case of a C# application using VMR, the threading model employed may not allow this call to function at all.
The more optimal approach is to catch the mtStartStreamDone event in the application, which is fired by the client at the same time this Boolean changes state internally (for example, the same information can be caught instead of polled).
Examples
C# Example
if (!this.axc.mtStreamStarting()) {// Use other AxClient APIs to modify the stream.}JavaScript Example
if(!axc.mtStreamStarting()) { //call other Axclient APIs}else {//error out}Related Methods
mtStartStreamWait
HRESULT mtStartStreamWait (ULONG msec);
Purpose
Pauses the AxClient for a specified number of milliseconds after invoking the mtStartStream method, before invoking another method, or until the mtStartStream command is finished, whichever occurs first.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
You can use the mtStartStreamWait and the mtStreamStarting methods to determine whether to wait before invoking another method. If the mtstreamStarting indicates that a stream is starting, you can use the mtStartStreamWait to cause the system to wait a few seconds before invoking another method.
Examples
C# Example
try {this.axc.mtStartStream(bwims://1.1.1.1/p_s1_CiscoHDCamera_1, 6, true);} catch(Exception ex) {this.logger.subLog("Exception in mtStartStream - " + ex.Message);}this.axc.mtStartStreamWait(2000);// Use other AxClient APIs to modify the stream.JavaScript Example
if (axc.mtStreamStarting()) {axc.mtStartStreamWait(2000);}// Use other AxClient APIs to modify the stream.Related Methods
playForward
HRESULT playForward (void);
Purpose
Plays the started archive video stream in the forward direction.
Arguments
This method has no arguments.
Return Values
HRESULT S_OK
Exceptions
None.
Events Fired
OnStateChanged
Notes
This method applies only to archive video streams.
Examples
C# Example
try{if (axc.getState() == "0"){axc.playForward();}else{//already streaming..}}catch (Exception error){this.logger.callbackLog("exception" + er}JavaScript Example
axc.playForward();Related Methods
playRewind
HRESULT playRewind (void);
Purpose
Plays the started archive video stream in the reverse direction.
Note
Arguments
This method has no arguments.
Return Values
HRESULT S_OK
Exceptions
None.
Events Fired
onStateChanged
Notes
This method applies only to archive video streams.
Examples
C# Example
this.axc.playRewind();JavaScript Example
axc.playRewind();Related Methods
stepForward
HRESULT stepForward (void);
Purpose
Moves the loaded archive video stream one frame in the direction of the current playback.
Note
Arguments
This method has no arguments.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
onStateChanged
Notes
This method applies only to archive video streams.
The step forward movement is in the same direction as the current play direction. For example, calling the playRewind method followed by the stepForward method moves the stream one frame backward.
Examples
C# Example
this.axc.stepForward();JavaScript Example
axc.stepForward();Related Methods
stepRewind
HRESULT stepRewind (void);
Purpose
Moves the loaded archive video stream one frame in the opposite direction of the current playback.
Note
Arguments
This method has no arguments.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
onStateChanged
Notes
This method applies only to archive video streams.
Operates in the reverse direction of the current play direction. For example, issuing playRewind() then stepRewind() moves the stream one step forward.
Examples
C# Example
this.axc.stepRewind();JavaScript Example
axc.stepRewind();Related Methods
pause
HRESULT pause (void);
Purpose
Pauses the playback of an archive or pauses a live source on the current frame.
Arguments
This method has no arguments.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
onStateChanged
Notes
The application must reload the stream (for example, call mtStartStream again) if the stream has been paused for more than 15 minutes. After 15 minutes of pause, the stream will no longer be loaded in memory and no subsequent API calls will have any effect on it.
Examples
C# Example
this.axc.pause();JavaScript Example
axc.pause();Related Methods
playResume
HRESULT playResume (void);
Purpose
Starts playing a previously paused stream and continues in the previous direction of play.
Arguments
This method has no arguments.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
onStateChanged
Notes
The application must reload the stream (for example, call mtStartStream again) if the stream has been paused for more than 15 minutes. After 15 minutes of pause, the stream will no longer be loaded in memory and no subsequent API calls will have any effect on it.
Examples
C# Example
this.axc.playResume();JavaScript Example
axc.playResume();Related Methods
stop
HRESULT stop (void);
Purpose
Stops streaming the live or archived video.
Arguments
This method has no arguments.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
onStateChanged
Notes
We do not recommend that you use this method. Use the close() method instead.
The video data buffer is flushed. However, properties are not unloaded, and get methods will still return valid information for the stream that is loaded. Because of the work associated with the buffer, stop is not recommended if the application will resume playback. If playback resumes within 15 minutes, pause is recommended instead.
Examples
C# Example
this.axc.stop();JavaScript Example
axc.stop();Related Methods
close
HRESULT close (void)
Purpose
Stops streaming the feed or archive and disconnects the AXclient from the VSMS host. Also flushes and resets source properties.
Arguments
This method has no arguments.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
onStateChanged
Notes
To reload the stream after calling the close method, you must use the mtStartStream method.
Because of the work associated with flushing the video buffer, we do not recommend using this method if the same video stream is to be viewed again in a relatively short time frame; instead, we recommend that you use the pause method.
This method does not have to be called if the client intends to call the mtStartStream method for another source in the next moment (for example, changing from one source to another). When the next mtStartStream method is initiated, the same buffer flush takes place, so placing a close at the end of a viewing session, right before the next session starts (in the same client), duplicates work.
Examples
C# Example
this.axc.close();JavaScript Example
axc.close();Related Methods
setPlayrateEx
HRESULT setPlayrateEx (Long playRate);
Purpose
Specifies the playback rate for a loaded archive.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
onPlayrateChanged
Notes
This method replaces the setPlayrate method, which should no longer be used.
Examples
C# Example
this.axc.setPlayRateEx(8);JavaScript Example
axc.setPlayRateEx(8);Related Methods
repeatUTCSegment
HRESULT repeatUTCSegment (
DOUBLE seekTime,
LONG startOffset,
LONG endOffset);Purpose
Plays a designated segment of an archive repeatedly (loops the segment).
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
onStateChanged
Notes
This method seeks the specified seektime in an archive and repeatedly plays the archive segment bounded by seekTime - startOffset and seekTime - endOffset. Units are in seconds. The endOffset argument is a positive number.
Examples
C# Example
this.axc.repeatUTCSegment(12345,1,120);JavaScript Example
axc.repeatUTCSegment(12345,1,120);Related Methods
seekToUTCTime
HRESULT seekToUTCTime (DOUBLE time);
Purpose
Seeks to the specified time in an archive. Time is stored as seconds since 1970.
Arguments
time
Start time of the segment in UTC format, representing the number of seconds since January 1, 1970.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
onStateChanged
Notes
Seeking should not be performed before the onStartOfStream event has been received. Wait for the onStartofStream event to fire before calling this API. This method replaces the seek() method, which should no longer be used and may not function as expected.
Examples
C# Example
double startTime = 0;startTime = axc.getUTCStartTime();axc.seekToUTCTime(startTime);JavaScript Example
axc.seekToUTCTime(12345678);Related Methods
seekToPercentage
HRESULT seekToPercentage (FLOAT percent);
Purpose
Seeks to the specified percentage in an archive.
Arguments
percent
Percentage of the total time of the archive. Valid values are in decimal format between 0 and 1.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
onSeekTimeChanged
Notes
Seeking should not be performed before the onStartOfStream event has been received. Wait for the onStartofStream event to fire before calling this API. This method replaces the seek() method, which should no longer be used and may not function as expected.
Examples
C# Example
axc.seekToPercentage(0.56);JavaScript Example
axc.seekToPercentage(0.56);Related Methods
showTimestamp
HRESULT showTimestamp (VARIANT_BOOL show);
Purpose
Shows or hides the timestamp overlay when playing a video source.
The timestamp overlay displays the time associated with each frame of the stream. This call can only be made after the stream is playing. Calling showTimestamp before the stream is actually playing will result in an error. This API only applies to MPEG2 sources.
Arguments
show
Controls whether the timestamp displays:
•
•
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
By default, timestamps are not displayed.
Examples
C# Example
// This example uses a UI checkbox to determine if timestamp should be on or off,// and then executes that choice once the onStartofStream event has fired// (timestamp cannot be set prior to this point).protected void axc_OnStartOfStream(object sender,_IMediaPlayerCtrlEvents_OnStartOfStreamEvent e){if (this.timestampOption.Checked) {axc.showTimestamp(true);} else if (!this.timestampOption.Checked) {axc.showTimestamp(false);}}JavaScript Example
axc.showTimestamp(true);Related Methods
None.
addToSync
HRESULT addToSync (
BSTR aSyncId,
SHORT aCount);Purpose
Allows a client playback window to perform the identical operations that other windows are performing.
This is helpful when viewing a number of archives for a given time period and you desire all the archives to shuttle through the archive set in the same manner (for example, every window starts playing at the same seek point, every window pauses at the same time, etc.).
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
This API requires user intervention during the execution of the request. For a headless API to perform the clip save, use the save method instead.
For VSM 6.3.2 or higher, this method is supported in both JavaScript and C#; for VSM 6.3, this method is supported only in JavaScript.
Examples
C# Example
axc.addToSync("12345678",1);JavaScript Example
axc.addToSync("12345678",1);Related Methods
removeFromSync
HRESULT removeFromSync ();
Purpose
Removes a client playback window from sync control.
Sync control performs the identical operations that other windows are performing, which is helpful when viewing a number of archives for a given time period and you desire all the archives to shuttle through the archive set in the same manner (for example, every window starts playing at the same seek point, every window pauses at the same time, etc.).
Arguments
This method has no arguments.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
This API requires user intervention during the execution of the request. For a headless API to perform the clip save, use the save method instead.
For VSM 6.3.2 or higher, this method is supported in both JavaScript and C#; for VSM 6.3, this method is supported only in JavaScript.
Examples
C# Example
axc.removeFromSync();JavaScript Example
axc.removeFromSync();Related Methods
createSyncId
HRESULT addToSync (BSTR *aSyncId);
Purpose
Creates a string that can be used for client synchronization.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
Not recommended for creating a unique string. A GUID generator produces a more unique string and is recommended instead.
Examples
C# Example
string aSyncId = axc.createSyncId();JavaScript Example
string aSyncId = axc.createSyncId();Related Methods
Methods for Obtaining Information about the AxClient or Video Streams
The following sections describe the methods that provide functionality for obtaining information about the AxClient and about video streams.
getCiscoHD
HRESULT getCiscoHD ();
Purpose
Indicates whether the stream comes from a Cisco high definition IP camera.
Arguments
None.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
int HD = axc.getCiacoHD()
JavaScript Example
var HD = axc.getCiacoHD()
Related Methods
None.
getVersion
HRESULT getVersion (BSTR *version);
Purpose
Retrieves the version number of the AxClient.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
The version of imsclient.dll is returned.
Examples
C# Example
String myVersion = axc.getVersion();JavaScript Example
var myVersion = axc.getVersion();Related Methods
None.
getUTCSeekTime
HRESULT getUTCSeekTime (DOUBLE ptime);
Purpose
Retrieves the seek time in UTC format.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
This method is not supported for live feeds.
Examples
C# Example
double mySeekTime axc.getUTCSeekTime();JavaScript Example
var mySeekTime = axc.getUTCSeekTime();Related Methods
getUTCStartTime
HRESULT getUTCStartTime (DOUBLE *ptime);
Purpose
Retrieves the start time of an archive in UTC format.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the stream is paused, the AxClient does not receive an update for the start or stop times of a loop archive until it resumes playing. For looping archives, the start time of which a paused client is aware could be incorrect (until the client begins playing once again and receives the next start time update).
Examples
C# Example
double startTime = 0;startTime = axc.getUTCStartTime();axc.seekToUTCTime(startTime);JavaScript Example
var startTime = axc.getUTCStartTime();axc.seekToUTCTime(startTime);Related Methods
getUTCStopTime
HRESULT getUTCStopTime (DOUBLE *ptime);
Purpose
Retrieves the last frame time of the archive, in UTC format.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the stream is paused, the AxClient does not receive an update for the start or stop times of a loop archive until it resumes playing. For looping archives, the start time of which a paused client is aware could be incorrect (until the client begins playing once again and receives the next start time update).
Examples
C# Example
double stopTime = 0;stopTime = axc.getUTCStopTime();axc.seekToUTCTime(stopTime);JavaScript Example
var stopTime = axc.getUTCStopTime();axc.seekToUTCTime(stopTime);Related Methods
getUTCCurrentTime
HRESULT getUTCCurrentTime (Double *ptime);
Purpose
Retrieves the current time in an archive, in UTC format.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the stream is paused, the AxClient does not receive an update for the start or stop times of a loop archive until it resumes playing. For looping archives, the start time of which a paused client is aware could be incorrect (until the client begins playing once again and receives the next start time update).
Examples
C# Example
double currentTime = 0;currentTime = axc.getUTCCurrentTime();axc.seekToUTCTime(currentTime);JavaScript Example
var currentTime = axc.getUTCCurrentTime();Related Methods
getUTCOriginalStartTime
HRESULT getUTCOriginalStartTime (DOUBLE *ptime);
Purpose
Retrieves the actual start time for a loop archive, in UTC format.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the stream is paused, the AxClient does not receive an update for the start or stop times of a loop archive until it resumes playing. For looping archives, the start time of which a paused client is aware could be incorrect (until the client begins playing once again and receives the next start time update).
Examples
C# Example
double startTime = axc.getUTCOriginalStartTime();JavaScript Example
var startTime = axc.getUTCOriginalStartTime();Related Methods
getState
HRESULT getState (BSTR *state);
Purpose
Retrieves the state of the player.
Arguments
state
The current state of a the player:
•
•
•
•
•
•
•
•
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
Based on the called control operation, the state of the AXclient changes, When the state changes, the AX client also fires the onStateChange event.
Examples
C# Example
string playerState = axc.getState();JavaScript Example
var playerState = axc.getState();Related Methods
Methods for Controlling Video Operations
getContentType
HRESULT getContent (BSTR *state);
Purpose
Retrieves the media type of a loaded source.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
string playerContent = axc.getContentType();JavaScript Example
var playerContent = axc.getContentType();Related Methods
getCurrentSource
HRESULT getCurrentSource (BSTR *pSource);
Purpose
Retrieves the URL of the currently loaded source.
Arguments
pSource
Video source in the format //host/source, where:
•
•
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
string playerSource = axc.getCurrentSource();JavaScript Example
var playerSource = axc.getCurrentSource();Related Methods
getRecordrateEx
HRESULT getRecorderateEx (DOUBLE *recordRate);
Purpose
Retrieves the rate at which the archive was recorded. Depending on the media type of the source, this value is the framerate or the bitrate.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
The information that this method provided depends on the media type of the source. For JPEG sources, this value is the framerate. For MPEG sources, this value is the bitrate.
This method does not apply to live feeds. Live feeds return -1.
Caution
Examples
C# Example
double myFrameRate = axc.getRecordrateEx();JavaScript Example
var myFrameRate = axc.getRecordrateEx();Related Methods
getPlayrateEx
HRESULT getPlayrateEx (DOUBLE *playRate);
Purpose
Retrieves the rate at which the loaded archive is playing.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
double myFrameRate = axc.getRecordrateEx();JavaScript Example
var myFrameRate = axc.getRecordrateEx();Related Methods
getErrorText
HRESULT getErrorText (
VARIANT errorCode,
BSTR* errorText);Purpose
Retrieves the text description of the specified error code.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
string strError = axc.getErrorText();JavaScript Example
var error = axc.getErrorText();Related Methods
None.
getProfiles
HRESULT getProfiles (
BSTR source,
VARIANT *profiles);Purpose
Retrieves a list of the WMV profiles that the loaded video stream supports.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
CBR means constant bitrate and VBR means variable bitrate.
Examples
C# Example
string[] profiles = axc.getProfiles("bwims://10.10.100.200/NorthEntrance");JavaScript Example
var profiles = axc.getProfiles();var profileArray = profile.toArray("bwims://10.10.100.200/NorthEntrance");Related Methods
getProfilesSSV
HRESULT getProfilesSSV (
BSTR source,
BSTR* profiles);Purpose
Retrieves an array of strings that represent the WMV profiles that the loaded video stream supports.
Arguments
source
Video source from which to obtain the array of strings.
profiles
Array of strings that represent the WMV profiles.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
CBR means constant bitrate and VBR means variable bitrate.
Examples
C# Example
string profiles = axc.getProfilesSSV("bwims://10.10.100.200/NorthEntrance");JavaScript Example
var profiles = axc.getProfilesSSV();var profileArray = profile.toArray("bwims://10.10.100.200/NorthEntrance");Related Methods
getStreamCodecSubtype
HRESULT getStreamCodecSubtype (INT *subtype);
Purpose
Retrieves the subtype of the codec of the loaded stream.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
int streamTypeInt = axc.getStreamCodecSubtype();JavaScript Example
var streamType = axc.getStreamCodecSubtype();Related Methods
getVideoWidth
HRESULT getVideoWidth (SHORT *width);
Purpose
Gets the width of the source stream, in pixels.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
The actual source width may differ from the width that the source should be displayed.
Examples
C# Example
short videoW= axc.getVideoWidth();JavaScript Example
var videoW = axc.getVideoWidth();Related Methods
getVideoHeight
HRESULT getVideoHeight (SHORT *height);
Purpose
Gets the height of the source stream, in pixels.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
The actual source height may differ from the height that the source should be displayed.
Examples
C# Example
short videoH = axc.getVideoHeight();JavaScript Example
var videoH = axc.getVideoHeight();Related Methods
getDisplayWidth
HRESULT getDisplayWidth (SHORT *width);
Purpose
Gets the width in pixels at which the source should be displayed.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
The actual source width may differ from the width that the source should be displayed.
Examples
C# Example
short displayW = axc.getDisplayWidth();JavaScript Example
var displayW = axc.getDisplayWidth();Related Methods
getDisplayHeight
HRESULT getDisplayHeight (SHORT *height);
Purpose
Gets the height in pixels at which the source should be displayed.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
The actual source height may differ from the height that the source should be displayed.
Examples
C# Example
short displayH = axc.getDisplayHeight();JavaScript Example
var displayH = axc.getDisplayHeight();Related Methods
getX
HRESULT getX (DOUBLE *x);
Purpose
Retrieves the x coordinate of the center of the view rectangle.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
double xCoord = axc.getX();JavaScript Example
var xCoord = axc.getX();Related Methods
getY
HRESULT getY (DOUBLE *y);
Purpose
Retrieves the y coordinate of the center of the view rectangle.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
double yCoord = axc.getY();JavaScript Example
var yCoord = axc.getY();Related Methods
Methods for Creating Clips and Snapshots
The following sections describe the methods that provide functionality for creating clips and snapshots from archived video.
Table 6-3 API Method Summary
Creates a clip of the video archive file with the .cva filename extension.
saveInPortableFormat
HRESULT saveInPortableFormat (
BSTR source,
BSTR startTime,
BSTR stopTime,
BSTR destination,
BSTR profile);Purpose
Saves a clip in WMV format. A profile window pops up once this API has been called, and the user must select the desired WMV format for the saved file.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
This API requires user intervention during the execution of the request. For a headless API to perform the clip save, use the save method instead.
Examples
C# Example
long startTime = (long)Math.Round(axc.getUTCStartTime());long endingTime = (long)Math.Round(axc.getUTCStopTime());//convert the getUTCdate seconds to the milliseconds required by this calllong startTimeMS = startTime * 1000;long clipEndTimeMS = endingTime * 1000;try {axc.saveInPortableFormat("bwims://myServer/myArchive",startTimeMS.ToString(),clipEndTimeMS.ToString(),"c:\temp.wmv","");} catch (Exception ex) {threadSafeSet2Text(ex.Message);}JavaScript Example
/** Save Clip (wmv)* @param sourceURL bwims:// url* @param startUTC start time in UTC milliseconds* @param stopUTC end time in UTC milliseconds* @param filePath local client path to save the generated clip. null value will to prompt user*/clipPortable : function(sourceURL, startUTC, stopUTC, filePath) {try {if (!this.axc.mtStreamStarting()) {sourceURL = new String(sourceURL);startUTC = new String(startUTC);stopUTC = new String(stopUTC);filePath = (null == filePath) ? '' : new String(filePath);this.axc.saveInPortableFormat(sourceURL, startUTC, stopUTC, filePath, '');} else {alerts(TEXT['js-stream-not-loaded']);}} catch(ex) { this.setError(ex) }}Related Methods
createCiscoVideoArchive
HRESULT createCiscoVideoArchive (BSTR xmlStreamInfo);
Purpose
Creates a clip of the video archive file with the .cva filename extension.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
The CVA format supports creating clips with multiple video sources, such as a view in VSOM. The CVA clips can be played using Cisco Review Player.
Examples
C# Example
axc.createCiscoVideoArchive("<?xml version="1.0" encoding="UTF-8"?><createCiscoVideoArchive><layoutName>1X1</layoutName><clipTime><begin>1271021709</begin><end>1271022009</end></clipTime><grid><row><cell><cameraName>My2600Archive</cameraName><uri>bwims://MyServer/My2600Archive</uri></cell><cell><cameraName>My4500Archive</cameraName><uri>bwims://MyServer/My4500Archive</uri></cell></row></grid></createCiscoVideoArchive>");JavaScript Example
axc.createCiscoVideoArchive("<?xml version="1.0" encoding="UTF-8"?><createCiscoVideoArchive><layoutName>1X1</layoutName><clipTime><begin>1271021709</begin><end>1271022009</end></clipTime><grid><row><cell><cameraName>My2600Archive</cameraName><uri>bwims://MyServer/My2600Archive</uri></cell><cell><cameraName>My4500Archive</cameraName><uri>bwims://MyServer/My4500Archive</uri></cell></row></grid></createCiscoVideoArchive>");Related Methods
snapshot
HRESULT snapshot (void);
Purpose
Saves the current frame of video to the viewing client computer. Opens a Windows dialog box in which users can choose to save in a number of image formats, including BMP, GIF, JPEG, PNG, and TIFF.
Arguments
This method has no arguments.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
The file types that are supported by this call are BMP, GIF, JPEG, PNG, and TIFF.
Examples
C# Example
You cannot programmatically save the file: the user must enter data in the pop-up window.
JavaScript Example
You cannot programmatically save the file: the user must enter data in the pop-up window.
Related Methods
getSnapshotDIB
HRESULT getSnapshotDIB ();
Purpose
Creates a snapshot of the current frame in standard Windows device-independent bitmap (DIB) format that can be saved to a .bmp file.
Arguments
This method has no arguments.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
Follow the example provided here to generate a proper BMP file.
The difference between getSnapshotDIB and getSnapshotWin32DIB is that getSnapshotDIB returns a properly formed bitmap, while getSnapshotWin32DIB returns a bit array including the bitmap info header, the raw bitmap data, and extra characters that must be parsed out before the payload from the API can be consumed.
Examples
C# Example
object bmpFromArchive = axc.getSnapshotDIB();//convert the object to a byte[]BinaryFormatter bf = new BinaryFormatter();MemoryStream ms = new MemoryStream();bf.Serialize(ms, bmpFromArchive);byte[] data = ms.ToArray();string clientSnapShotLocation ="c:\\Client2Snapshot" +DateTime.UtcNow.ToString("yyMMddHmmss") +".bmp";FileStream fileStream = new FileStream(clientSnapShotLocation, FileMode.Create);fileStream.Write(data, 0, data.Length);fileStream.Close();JavaScript Example
None.
Related Methods
getSnapshotWin32DIB
HRESULT getSnapshotWin32DIB (VARIANT *pDIB);
Purpose
Creates a snapshot of the current frame in standard Windows device-independent bitmap (DIB) format that can be saved to a .bmp file.
Caution
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
Follow the example provided here to generate a proper BMP file.
The difference between getSnapshotDIB and getSnapshotWin32DIB is that getSnapshotDIB returns a properly formed bitmap, while getSnapshotWin32DIB returns a bit array including the bitmap info header, the raw bitmap data, and extra characters that must be parsed out before the payload from the API can be consumed.
Examples
C# Example
//get snapshot, return an objectobject bmpFromArchive = axc.getSnapshotWin32DIB();//convert the object to a byte[]BinaryFormatter bf = new BinaryFormatter();MemoryStream ms = new MemoryStream();bf.Serialize(ms, bmpFromArchive);byte[] data = ms.ToArray();// The first 13 bytes need to be trimmed off when writing to file (or using in any other manner).// The next 14 bytes need to be formatted as a valid BITMAPFILEHEADER.int j = 13; //this value may need to change based on VMR control outputint size = (data.Length - j);//fill the 14 byte headerdata[j] = 0x42;data[j + 1] = 0x4d;BitConverter.GetBytes(size).CopyTo(data, j + 2);data[j + 6] = 0;data[j + 7] = 0;data[j + 8] = 0;data[j + 9] = 0;data[j + 10] = 0x36;data[j + 11] = 0;data[j + 12] = 0;data[j + 13] = 0;// Now the byte array is correct, from byte 14 forwardstring clientSnapShotLocation = "c:\\Client1Snapshot" +DateTime.UtcNow.ToString("yyMMddHmmss") +".bmp";FileStream fileStream = new FileStream(clientSnapShotLocation, FileMode.Create);fileStream.Write(data, j, data.Length - j);fileStream.Close();JavaScript Example
None.
Related Methods
Methods for Controlling VMR Display
The following sections describe the methods that provide functionality for controlling a Video Mixing Renderer (VMR) display.
setAlpha
HRESULT setAlpha (DOUBLE alpha);
Purpose
Sets the transparency level of the VMR filter.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the VMR is not turned on via the AxClient bag property, this call will have no effect.
Examples
C# Example
axc.setAlpha(1)JavaScript Example
axc.setAlpha(1)Related Methods
getAlpha
HRESULT getAlpha (DOUBLE *alpha);
Purpose
Retrieves the transparency level of the VMR.
Arguments
None.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the VMR is not turned on via the AxClient bag property, this call will have no effect.
Examples
C# Example
double alpha = axc.getAlpha()JavaScript Example
var alpha = axc.getAlpha()Related Methods
setTransparent
HRESULT setTransparent (LONG rgb);
Purpose
Sets the transparent color and updates the alpha bitmap.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the VMR is not turned on via the AxClient bag property, this call will have no effect.
Examples
C# Example
axc.setTransparent(8034025)JavaScript Example
axc.setTransparent(8034025)Related Methods
getTransparent
HRESULT getTransparent (LONG *rgb);
Purpose
Retrieves the transparent color in the stream.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the VMR is not turned on via the AxClient bag property, this call will have no effect.
Examples
C# Example
long rgb = axc.getTransparent()JavaScript Example
var rgb = axc.getTransparent()Related Methods
setBaseRectColor
HRESULT setBaseRectColor (LONG rgb);
Purpose
Sets the base rectangle color and updates the alpha bitmap of the loaded video.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the VMR is not turned on via the AxClient bag property, this call will have no effect.
Examples
C# Example
axc.setBaseRectColor(13474304)JavaScript Example
axc.setBaseRectColor(13474304)Related Methods
getBaseRectColor
HRESULT getBaseRectColor (LONG *rgb);
Purpose
Retrieves the base rectangle color of the loaded stream.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the VMR is not turned on via the AxClient bag property, this call will have no effect.
Examples
C# Example
long rgb = axc.getBaseRectColor()JavaScript Example
var rgb = axc.getBaseRectColor()Related Methods
setZoomRectColor
HRESULT setZoomRectColor (LONG rgb);
Purpose
Sets the zoom rectangle color and updates the alpha bitmap of the loaded stream.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the VMR is not turned on via the AxClient bag property, this call will have no effect.
Examples
C# Example
axc.setZoomRectColor(15643136)JavaScript Example
axc.setZoomRectColor(15643136)Related Methods
getZoomRectColor
HRESULT getZoomRectColor (LONG rgb);
Purpose
Retrieves the zoom rectangle color.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the VMR is not turned on via the AxClient bag property, this call will have no effect.
Examples
C# Example
long rgb = axc.getZoomRectColor()JavaScript Example
var rgb = axc.getZoomRectColor()Related Methods
setTimeStampRect
HRESULT setTimeStampRect (
LONG left,
LONG top,
LONG right,
LONG bottom);Purpose
Sets the time stamp rectangle and updates the alpha bitmap.
Arguments
left
Left coordinate of the rectangle.
top
Top coordinate of the rectangle.
right
Right coordinate of the rectangle.
bottom
Bottom coordinate of the rectangle.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the VMR is not turned on via the AxClient bag property, this call will have no effect.
Examples
C# Example
axc.setTimeStampRect(1,3,5,1)JavaScript Example
axc.setTimeStampRect(1,3,5,1)Related Methods
None.
setVmrDisplayMode
HRESULT setVmrDisplayMode (SHORT displayMode);
Purpose
Sets the VMR display mode.
This places the zoom reticule on screen or hides the zoom reticule (default). This does not enable VMR (the bag property associated with imsclient.dll includes this setting and enables VMR).
Arguments
displayMode
VMR display mode:
•
•
The default value is 0.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the VMR is not turned on via the AxClient bag property, this call will have no effect.
Examples
C# Example
axc.setVmrDisplayMode(1);JavaScript Example
axc.setVmrDisplayMode(1);Related Methods
getVmrDisplayMode
HRESULT getVmrDisplayMode (SHORT *displayMode);
Purpose
Gets the VMR display mode.
This indicates that either the zoom reticule is on screen or the zoom reticule is hidden (default). This does not enable VMR (the bag property associated with imsclient.dll includes this setting and enables VMR).
Arguments
displayMode
VMR display mode:
•
•
The default value is 0.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the VMR is not turned on via the AxClient bag property, this call will have no effect.
Examples
C# Example
short displayMode = axc.getVmrDisplayMode();JavaScript Example
var displayMode = axc.getVmrDisplayMode();Related Methods
setZoomFactor
HRESULT setZoomFactor (DOUBLE val);
Purpose
Sets the zoom factor and updates the display.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the VMR is not turned on via the AxClient bag property, this call will have no effect.
Examples
C# Example
axc.setZoomFactor(2)JavaScript Example
axc.setZoomFactor(2)Related Methods
getZoomFactor
HRESULT getZoomFactor (DOUBLE *val);
Purpose
Retrieves the zoom factor.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
If the VMR is not turned on via the AxClient bag property, this call will have no effect.
Examples
C# Example
double rgb = axc.getZoomFactor()JavaScript Example
var rgb = axc.getZoomFactor()Related Methods
move
HRESULT move (
DOUBLE x,
DOUBLE y);Purpose
Changes the size of the viewing rectangle and updates the display.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
This is the underlying function to which resizeVideoWindow forwards.
Examples
C# Example
//To view video in a 640x480 rectangleaxc.Move(640, 480);JavaScript Example
axc.Move(640,480);Related Methods
deltaMove
HRESULT deltaMove (
DOUBLE x,
DOUBLE y);Purpose
Changes the view (zoom) rectangle by an increment and updates the display.
Arguments
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
//To view video in a 640x480 rectangleaxc.deltaMove(640, 480);JavaScript Example
axc.deltaMove(640,480);Related Methods
resizeVideoWindow
void resizeVideoWindow (
int owner
int x,
int y,
int w,
int h);Purpose
Changes both the rectangle size (zoom) and the video window X and Y co-ordinates.
Arguments
owner
The handle of the target display window
x
New x coordinate of the video window.
y
New y coordinate of the video window.
w
New width of the video window.
h
New height of the video window.
Return Values
HRESULT S_OK/E_FAIL
Exceptions
None.
Events Fired
None.
Notes
This method is similar to the move method, except that the move method does not actually move the window. It relocates the window to the coordinates provided by the X and Y input parameters. The correct handle of the target display window must be provided to the Owner input parameter or this call will not have a visible impact on the display.
Examples
C# Example
//This will resize the window to a 640x480 rectangle//in the upper left-most corner of the screenthis.axc.ResizeVideoWindow((int)this.axc.Handle,1,1,640,480);JavaScript Example
axc.ResizeVideoWindow(axc,1,1,640,480);Related Methods
Methods for Setting up Callbacks
The following sections describe the methods that provide functionality for setting up callbacks.
setOnEndOfStream
void setOnEndOfStream (String callbackFunction);
Purpose
Invokes the specified user-defined callback function when an archive stops playing.
Arguments
Return Values
None.
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
axc.setOnEndOfStream('callback_SetOnEndOfStream');function callback_SetOnEndOfStream(name){}JavaScript Example
axc.setOnEndOfStream('callback_SetOnEndOfStream');function callback_SetOnEndOfStream(name){}Related Methods
setOnMtStartStreamDone
void setOnMtStartStreamDone (String callbackFunction);
Purpose
Invokes the specified user-defined callback function when an archive playback is initiated.
Arguments
Return Values
None.
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
axc.setOnMtStartStreamDone('callback_SetOnMtStartStreamDone');function callback_SetOnMtStartStreamDone(name) {//Check if the stream is loaded and ready for more commandsif (axc.mtStreamStarting()){axc.mtStartStreamWait(100);}}JavaScript Example
axc.setOnMtStartStreamDone('callback_SetOnMtStartStreamDone');function callback_SetOnMtStartStreamDone(name) {//Check if the stream is loaded and ready for more commandsif (axc.mtStreamStarting()){axc.mtStartStreamWait(100);}}Related Methods
setOnPlayrateChanged
void setOnPlayrateChanged (String callbackFunction);
Purpose
Invokes the specified user-defined callback function when an archive play rate changes.
Arguments
Return Values
None.
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
axc.setOnPlayrateChanged('callback_SetOnPlayrateChanged');function callback_SetOnPlayrateChanged(name, playRate) {}JavaScript Example
axc.setOnPlayrateChanged('callback_SetOnPlayrateChanged');function callback_SetOnPlayrateChanged(name, playRate) {}Related Methods
setOnSaveResponse
void setOnSaveResponse (String callbackFunction);
Purpose
Invokes the specified user-defined callback function when a previously initiated save clip has finished.
Arguments
Return Values
None.
Exceptions
None.
Events Fired
None.
Notes
The server response is the result of the initial save methods.
Examples
C# Example
axc.setOnSaveResponse('callback_SetOnSaveResponse');function callback_SetOnSaveResponse(name, success, confirm, location, message) {}JavaScript Example
axc.setOnSaveResponse('callback_SetOnSaveResponse');function callback_SetOnSaveResponse(name, success, confirm, location, message) {}Related Methods
setOnSeekTimeChanged
void setOnSeekTimeChanged (String callbackFunction);
Purpose
Invokes the specified user-defined callback function when an archive seek time changes.
Arguments
Return Values
None.
Exceptions
None.
Events Fired
None.
Notes
The callback function is invoked when a seek method has completed.
Examples
C# Example
axc.setOnSeekTimeChanged('callback_SetOnSeekTimeChanged');function callback_SetOnSeekTimeChanged(name, seekTime) {}JavaScript Example
axc.setOnSeekTimeChanged('callback_SetOnSeekTimeChanged');function callback_SetOnSeekTimeChanged(name, seekTime) {}Related Methods
setOnStartOfStream
void setOnStartOfStream (String callbackFunction);
Purpose
Invokes the specified user-defined callback function when an archive playback is initiated.
Arguments
Return Values
None.
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
axc.setOnStartOfStream('callback_SetOnStartOfStream');function callback_SetOnStartOfStream(name) {}JavaScript Example
axc.setOnStartOfStream('callback_SetOnStartOfStream');function callback_SetOnStartOfStream(name) {}Related Methods
setOnStartTimeChanged
void setOnStartTimeChanged (String callbackFunction);
Purpose
Invokes the specified user-defined callback function when an archive start time changes.
Arguments
Return Values
None.
Exceptions
None.
Events Fired
None.
Notes
This callback occurs approximately every second when VSMS updates the archive properties or when a new archive source is loaded. When the stream is paused, information is not being passed to AxClient so the start and stop time updates will not trigger.
Examples
C# Example
axc.setOnStartTimeChanged('callback_SetOnStartTimeChanged');function callback_SetOnStartTimeChanged(name, startTime) {}JavaScript Example
axc.setOnStartTimeChanged('callback_SetOnStartTimeChanged');function callback_SetOnStartTimeChanged(name, startTime) {}Related Methods
setOnStateChanged
void setOnOnStateChanged (String callbackFunction);
Purpose
Invokes the specified user-defined callback function when an archive playback state changes.
Arguments
Return Values
None.
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
axc.setOnStateChanged('callback_SetOnStateChanged');function callback_SetOnStateChanged(name, state) {}JavaScript Example
axc.setOnStateChanged('callback_SetOnStateChanged');function callback_SetOnStateChanged(name, state) {}Related Methods
Methods for Controlling Video Operations
setOnStopTimeChanged
void setOnStopTimeChanged (String callbackFunction);
Purpose
Invokes the specified user-defined callback function when an archive stop time changes.
Arguments
Return Values
None.
Exceptions
None.
Events Fired
None.
Notes
None.
Examples
C# Example
axc.setOnStopTimeChanged('callback_SetOnStopTimeChanged');function callback_SetOnStopTimeChanged(name, stopTime) {}JavaScript Example
axc.setOnStopTimeChanged('callback_SetOnStopTimeChanged');function callback_SetOnStopTimeChanged(name, stopTime) {}Related Methods
