IMessenger::SendFile method
[SendFile is no longer available for use as of Windows Vista. See Windows Messenger for more information.]
Launches the Send File mode of a conversation window to a specified contact.
Syntax
HRESULT SendFile(
[in] VARIANT vContact,
[in] BSTR bstrFileName,
[out, retval] IDispatch **ppMWindow
);
Parameters
-
vContact [in]
-
Type: VARIANT
A VARIANT that can take as its value either a VT_BSTR string or a VT_DISPATCH pointer to an existing MessengerContact object. If the input value type is a string, this method creates a new MessengerContact object internally. The string should be the full sign-in name. For a Microsoft .NET Messenger Service contact, this should include the "@" symbol and domain name. If the input value type is a pointer to an existing MessengerContact object (should be type VT_DISPATCH), the existing object is used.
-
bstrFileName [in]
-
Type: BSTR
A BSTR specifying the name and local path of the file to send. If a valid value is passed into this parameter (NULL or empty string, and is less than or equal to 260 characters) then a standard File dialog box is displayed, allowing the user to specify a file to send. If a path is specified with the file name, the dialog box will open in that directory. Specifying a file name for bstrFileName populates the dialog box and does not attempt to validate or determine that the specified file exists.
-
ppMWindow [out, retval]
-
Type: IDispatch**
A pointer to a pointer to the IDispatch interface on a MessengerWindow object, which can be accessed through the IMessengerWindow interface that is used to call other automation-accessible properties, such as Height, Width, Top, Left, and Show
Return value
Type: HRESULT
Returns one of the following values.
| Return code | Description |
|---|---|
|
Success. |
|
bstrFileName exceeded 260 characters. - or - vContact value is NULL, the wrong type, points to a NULL string, or points to a string that has a space as the first character. - or - vContact is VT_BSTR that exceeded 129 characters. - or - bstrFileName is VT_BSTR and contains a carriage return, or linefeed. |
|
ppMWindow is a NULL pointer. |
|
Client is not signed in to the primary service at the time this method was called. |
|
This method was called against the local client user. |
Remarks
Both the sender and receiver clients must be capable of file transfer, which is potentially affected by firewalls, user preferences, routing, and so on. If no preexisting conversation window has been sent, a new one is created on the local client. A file can also be sent through an existing conversation window. It is not necessary to send text in order to initiate the file transfer.
The destination contact must accept or decline the file transfer. Because this method is asynchronous, there is no way to know through the API whether the destination user has accepted or declined. The status of the file transfer can be read through system messages in the conversation window created by this method.
If successful, calling this method will either open a new conversation window or send an existing one to the foreground of the destination contact's computer. If the window is not in the foreground on the destination client, it may initially appear as a pop-up message on the system tray. If a conversation window is already open to a session with the user specified by vContact (and ppMWindow has not been released), no new window is displayed, no specific HRESULT is returned (returns S_OK), and the existing window instance will be referenced by the IDispatch pointer in the return value.
All conversation windows will be closed if the client signs out. If the client goes offline, the MessengerWindow objects corresponding to those windows will become dereferenced and should be released. Calling APIs on these objects is no longer valid.
A client cannot open a message or invitation to the local client user. This will result in E_FAIL. In this case, check IsSelf or do a string comparison of vContact and MySigninName.
ppMWindow should be released when it is no longer needed.
Note
This method is available for scripting languages.
Requirements
| End of client support |
Windows XP |
| End of server support |
Windows Server 2003 |
| Header |
|
| IDL |
|
| DLL |
|