Automation (OLE)

ControlGetInfo: String
Retrieves a line of text containing the Hamster-version and -path (for "Hello World!"-purposes ...).

ControlGetPath: String
Retrieves the path of the currently registered und used automation-server (i.e. path to last used "Hamster.exe")

ControlGetVersion: String
Retrieves the Hamster-versionnumber as a string ("1.3.0.16").

ControlSetLogin(Identifier, Username, Password: String)
Temporarily sets username and password for the given identifier, which can be either the name of a RAS-connection or the name of a news-/mail-server. "Temporarily" means, that this setting is not saved to a file but is kept in memory until Hamster is closed again.
If username and/or password is set to a single question-mark ("?"), Hamster will ask for the value when it's needed.
Furthermore, one of the stored ""general-purpose"-passwords can be selected here to avoid noting it in clear-text in the script, e.g. ControlSetLogin("serv.er", "$1", "").

ControlMessage(Msg, Param: Integer): Integer

HAM_MSG_HAMSTER_EXIT = 1
HAM_MSG_RESET_COUNTERS = 2
HAM_MSG_LOCALNNTP_ONOFF = 3
HAM_MSG_LOCALPOP3_ONOFF = 4
HAM_MSG_LOCALSMTP_ONOFF = 5
HAM_MSG_SHOWWINDOW = 6
HAM_MSG_SHOWICON = 7
HAM_MSG_STOPALLTASKS = 8

Initiates some Hamster-functions, which are normally available and accessed by menu-items.

Msg Param purpose

1  ignored    Exit Hamster
2  ignored    Reset counters and log
3  0=stop, 1=start    Start/Stop local NNTP-server
4  0=stop, 1=start    Start/Stop local POP3-server
5  0=stop, 1=start    Start/Stop local SMTP-server
6  0=hide, 1=show   Hide/show main-window
7  0=hide, 1=show   Hide/show tray-icon
8  ignored    Menu: Online/Stop all tasks

Return-values:

0   OK; command executed.
1   Error; command failed.
2   Unknown Msg-number.
3   GPF, please reboot ... ;-)

ControlIsIdle: Bool
Returns TRUE if there are currently no active tasks like purging, pulling news, sending mails etc.
Note: Client-connections to local servers and running scripts do not count as "active tasks" here.

ControlWaitIdle(WaitTimeout: Integer): Bool

Const HAM_WAITIDLE_INFINITE = 0
Like ControlIsIdle above, but this functions additionally waits the given amount of milliseconds, if there are active tasks. When called with WaitTimeout=0, the function does not return until all tasks have finished.
Note: See "Events: evtHamster.IsIdleAgain" for a better approach to wait until Hamster becomes "idle" again.
Note: Client-connections to local servers and running scripts do not count as "active tasks" here.

ControlThreadCount: Integer
Gives the number of currently active tasks.
Note: Client-connections to local servers and running scripts do not count as "active tasks" here.

ControlFlush: Integer
Writes unsaved data to disk. Suggested after last article imported with NewsImport.

ControlRunPurge(PurgeOptions: Integer): Integer

Const HAM_PURGEOPT_DOALL = 0xFF
Const HAM_PURGEOPT_DONEWS = 0x01
Const HAM_PURGEOPT_DOHISTORY = 0x02
Const HAM_PURGEOPT_DOKILLS = 0x04
Const HAM_PURGEOPT_DOMHISTORY = 0x08

Starts a purge-thread (i.e. the deletion of old data). The bit-oriented parameter PurgeOptions describes, which old data should be deleted (bit0=1=articles, bit1=2=history-entries, bit2=4=killfile-log, bit3=8=mailhistory-entries).

ControlRunRebuildHistory: Integer
Starts a thread, which deletes the current history-file (".\Groups\History.dat") and rebuilds it by adding the Message-IDs of all articles stored in Hamster.
Note: This may take some time with thousands of articles, so it should only be used, if it's really necessary! Be sure to wait until Hamster is idle again (e.g. with ControlWaitIdle) after calling this function!

ControlRunRebuildGlobalLists( Options: Integer ): Integer
Starts a thread, which rebuilds some lists needed by Hamster (see "Menu: File / Rebuild global lists" for details). No Options yet, so always use 0.

ControlRunMail(ServerList: String): Integer
Starts the thread, which first fetches new mails from the mailservers and then sends out mails (if any).
If ServerList is set to an empty string (""), all POP3- and SMTP-servers defined in Hamster may be used. Otherwise, transfer is restricted to the given servers.
If used, the ServerList has to consist of a semicolon-separated (";") list of servernames. The servernames have to be in the same format as displayed in the Hamster-settings (i.e. servername + "," + port).
Example: "mail.aaa.com,pop3;mail.bbb.com,pop3;mail.aaa.com,smtp"

ControlRunFetchMail(Server, Port, User, Pass, DestUser: String): Integer
Starts a thread, which fetches mails from the given POP3-server (Server, Port).
If User and Pass are given, they will be used to login to the server, if they are both empty, the password-setting for the given server is used. Furthermore, one of the stored "general-purpose"-passwords can be used here to avoid noting it in clear-text in the script (User="$(number)", Pass="").
If DestUser is given, fetched mails will be stored in the mailbox of this user, "admin"-mailbox is used otherwise. The name may optionally be followed by a comma and an identifier, which determines the filter-section to use for the mails fetched with this commands (default is global filters only, i.e. "[*]"-section in MailfFilt.hst).

Examples:

ControlRunFetchMail( "pop3.serv.er", "pop3", "", "", "" )
ControlRunFetchMail( "pop3.serv.er", "", "john.doe", "secret", "john" )
ControlRunFetchMail( "pop3.serv.er", "10110", "$7", "", "jane" )
ControlRunFetchMail( "pop3.serv.er", "", "$7", "", "admin,myfilters" )

ControlRunSendMail(Server, Port, FromSelection: String): Integer
Starts a thread, which sends mails to the given SMTP-server (Server, Port).
If no FromSelection is given, all mails waiting for delivery are sent. If a selection is given (regular expression), only mails with a matching Envelope-From are sent to this server.

Examples:

ControlRunSendMail( "smtp1.serv.er", "smtp", "john\.doe@serv\.er" )
ControlRunSendMail( "smtp2.serv.er", "", "" )

ControlRunSendMailAuth(Server, Port, User, Pass, FromSelection: String): Integer
Like ControlRunSendMail above, but additionally allows to provide username and password used for authentication.
Note: Username and password are ignored, if SMTP authentication is not enabled for the given server (see notes on SMTP authentication under "Mailserver").

Example:

ControlRunSendMailAuth( "smtp3.serv.er", "smtp", "$42", "", "@smtp3.serv.er" )

ControlRunNewsPost(ServerList: String): Integer
Starts the thread, which posts new articles (if any).
If ServerList is set to an empty string (""), all NNTP-servers defined in Hamster may be used. Otherwise, transfer is restricted to the given servers (see ControlRunMail for details on the ServerList-format).
Note: Starting with Hamster Vr. 1.3.19, this function was replaced with the NewsJobs*-functions described below and is only simulated internally with these new functions. See the example at "NewsJobsStart" for a replacement of this obsolete function.

ControlRunNewsPull(ServerList: String): Integer
Starts the threads, which pull new articles from newsservers.
If ServerList is set to an empty string (""), all NNTP-servers defined in Hamster may be used. Otherwise, transfer is restricted to the given servers (see ControlRunMail for details on the ServerList-format).
Note: Starting with Hamster Vr. 1.3.19, this function was replaced with the NewsJobs*-functions described below and is only simulated internally with these new functions. See the example at "NewsJobsStart" for a replacement of this obsolete function.

Other:

1. NewsJobsClear: Integer
2. NewsJobsPullDef(ServerList: String): Integer
3. NewsJobsPostDef(ServerList: String): Integer
4. NewsJobsPull(Servername, reGrpSelect: String): Integer
5. NewsJobsPost(Servername, reGrpSelect, reMsgSelect: String): Integer
6. NewsJobsStart(ServerList: String): Integer

These functions are identical to those used in Hamster-scripts.
For details, see the descriptions at:
HamNewsJobsClear, HamNewsJobsPullDef, HamNewsJobsPostDef, HamNewsJobsPull, HamNewsJobsPost, HamNewsJobsStart.

RasDial(ConnectionID, Username, Password: String): Bool
This function establishes the RAS-connection named ConnectionID.
The username and/or password can be set to empty strings (""). In this case, the ControlSetLogin-setting (if any) or the values stored in Hamster are used to establish the connection.
If dialing was successful (i.e. a connection was established), the function returns TRUE, otherwise FALSE (use RasLastError to get additional information on the failure).

RasHangup
Closes the current RAS-connection, even if not established by RasDial.

RasIsConnected: Bool
Returns TRUE, if there's a valid RAS-connection established by RasDial.

RasLastError: Integer
Returns the last RAS-errorcode (especially when RasDial returned FALSE).

NewsGrpCount: Integer
Retrieves number of newsgroups available from Hamster.

NewsGrpName(GrpIdx: Integer): String
Retrieves the name of the given newsgroup. GrpIdx can be 0 to (NewsGrpCount-1).

NewsGrpIndex(GrpName: String): Integer
Retrieves the index-number of the given groupname (-1 for unknown groups).

NewsGrpOpen(GrpName: String): Integer
Opens the given group and returns a handle (>=0), which is needed to retrieve additional infos in the functions below (the handle is referenced as GrpHdl there).
If the function fails, the return-value is negative (<0).

NewsGrpClose(GrpHdl: Integer)
Close a previously opened group.

NewsArtCount(GrpHdl: Integer): Integer
Retrieves the number of available articles in the group.

NewsArtNoMin(GrpHdl: Integer): Integer
Retrieve the lowest available article-number.

NewsArtNoMax(GrpHdl: Integer): Integer
Retrieve the highest available article-number.

NewsArtText(GrpHdl, ArtNo: Integer): String
Retrieves the text for the given article-number. An empty string indicates, that the article is not available any more.

NewsArtTextExport(GrpHdl, ArtNo: Integer): String
Same as NewsArtText, but the text is converted to export-format.

NewsScoreListFor(GrpName: String): String
Retrieves a list containing all score-entries, which will be used when pulling news for the given groupname.

NewsScoreTest(GrpName, ArtText: String; var MatchLog: String): Integer;
Returns the scorevalue for the given article (ArtText). The test is done with the assumption, that the article was pulled from the given newsgroup (GrpName). A CR/LF-separated list of all matching scorelines is returned in MatchLog.

NewsLocateMID(MessageID: String; var Groupname: String; var ArtNo: Integer): Bool;
Returns TRUE, if the given Message-ID is [still] saved in the history-file. In this case, Groupname and Article-number will be set to point to this article.
Otherwise the function returns FALSE and Groupname and article-number remain unchanged.
Note: Now the MID will be pulled by MID at the next pull.

NewsLocateMID2(MessageID: String; var Groupname: Variant; var ArtNo: Variant): Bool;
Same as "NewsLocateMid" above, but with Variant-parameters. Use this version in VBScript-scripts (Windows Script Host).

NewsDeleteByMID(MessageID: String): Bool;
Locates the article identified by the given Message-ID and deletes it in Hamster's database-files. The function returns TRUE, if article could be located and deleted; FALSE otherwise.

NewsImport(ArtText, OverrideGroups: String; IgnoreHistory, MarkNoArchive: Bool): Bool;
Imports the given article into Hamster's database and returns TRUE, if the article was imported, FALSE otherwise.

ArtText contains the article to import, including all headers, header/body-separator and the article-body. The lines have to be separated by CR+LF (0x0d, 0x0a).

If OverrideGroups is empty, the article is stored in the groups determined by the "Newsgroups:"-header of the article. Otherwise it is stored in the group given by OverrideGroups. If no valid local groups are given, the article is stored in hamster.misc.

If IgnoreHistory is TRUE, no history-lookup is made for the Message-ID of the imported article, so it will be imported even if it's already known.

If MarkNoArchive is TRUE, the imported article is marked with "NoArchive=1" in the "X-Hamster-Info:"-header. This flag might be used to mark the imported article as "temporary", so it can, for example, be ignored by appropriate archiving-software [not available yet ;-)].