Retrieves number of newsgroups available from Hamster.
Returns: >=0: OK/number of groups; <0: error
# see example at HamGroupName
Retrieves the name of the given newsgroup. <index> can be 0 to (HamGroupCount-1).
Returns: String
var( $grpidx ) $grpidx = 0 while( $grpidx < HamGroupCount ) print( HamGroupName( $grpidx ) ) inc( $grpidx ) endwhile
Retrieves the index-number of the given groupname.
Returns: >=0: OK/index-number; -1: unknown group
print( HamGroupIndex( "internal.misc" ) )
Opens the given group and returns a handle, 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).
Returns: >=0: OK/group-handle; <0: error
$grphdl = HamGroupOpen( "internal.misc" )
Closes a previously opened group.
Returns: 0
HamGroupClose( $grphdl )
Retrieves the number of available articles in the group.
Returns: >=0: OK/count, <0: error
# see example at HamArtText
Retrieve the lowest available article-number.
Returns: >=0: OK/count, <0: error
# see example at HamArtText
Retrieve the highest available article-number.
Returns: >=0: OK/count, <0: error
# see example at HamArtText
HamArtText( <grphdl>, <artno> )
Retrieves the text for the given article-number. An empty string indicates, that an article with the given number is not available (any more).
Returns: String (article-text or "")
var( $grpnam, $grphdl, $artmin, $artmax, $artno, $arttxt )
$grpnam = "internal.misc"
$grphdl = HamGroupOpen( $grpnam )
if( $grphdl >= 0 )
print( "Group ", $grpnam, ": ", HamArtCount($grphdl), " articles" )
$artmin = HamArtNoMin( $grphdl )
$artmax = HamArtNoMax( $grphdl )
$artno = $artmin
while( $artno <= $artmax )
$arttxt = HamArtText( $grphdl, $artno )
if( $arttxt <> "" )
print( "Article ", $artno, ": ", len($arttxt), " byte" )
endif
inc( $artno )
endwhile
HamGroupClose( $grphdl )
endif
Retrieves the text for the given Message-ID. An empty string indicates, that an article with the
given Message-ID is not available (any more).
Please note, that only Message-IDs of articles work here, that are within the "Days to keep
data: History" range. Older articles cannot be accessed by this function.
Returns: String (article-text or "")
$arttxt = HamArtTextByMid( "<aaa.bbb@ccc.ddd>" )
HamArtTextExport( <grphdl>, <artno> )
Same as "HamArtText", but the text is additionally converted to export-format.
Returns: String (article-text or "")
$arttxt = HamArtTextExport( $grphdl, $artno )
HamArtImport( <article>, <goverride>,
<ignorehist>, <marknoarch> )
...
HamArtImport( <article> )
Imports the given <article> into Hamster's database and returns TRUE, if the article was
imported, FALSE otherwise.
<article> 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 <goverride> is empty (default), the article is stored in the groups determined by the
"Newsgroups:"-header of the article. Otherwise it is stored in the group
given by <goverride>. If no valid local groups are given, the article is stored in internal.misc.
If <ignorehist> is TRUE (<>0), no history-lookup is made for the Message-ID of the
imported article, so it will be imported even if it's already known. Default is FALSE.
If <marknoarch> is TRUE (<>0), 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. Default is FALSE.
Returns: true/1: OK, false/0: error
HamArtImport( $article_text, "internal.misc" )
HamArtImportFile( <filename>,
<goverride>, <ignorehist>, <testonly> )
...
HamArtImportFile( <filename> )
Imports a file with given <filename>, that contains articles in "mbox" format.
If <goverride> is empty (default), the article is stored in the groups noted in the "Newsgroups:"-header
of imported articles. Otherwise it is stored in the group given by <goverride>. If no valid
local groups are given, the article is stored in internal.misc.
If <ignorehist> is TRUE (<>0), no history-lookup is made for the Message-ID of the
imported article, so it will be imported even if it's already known. Default is FALSE, i. e. don't
import already known articles.
If <testonly> is given and TRUE (<>0), the articles are not really imported but just
tested, if they can be imported. Default is FALSE, i. e. import the articles.
Returns: >=0: Number of imported articles, -1: File not found; -2: Unknown file format; -9: Error
HamArtImportFile( "articles.mbox" )
HamArtExportFile( <filename>,
<groupname>, <artnomin>, <artnomax> )
...
HamArtExportFile( <filename>, <groupname> )
Exports articles of group <groupname> to file <filename> in "mbox" format.
The range of article numbers to export can be selected by <artnomin> and <artnomax>. If
these values are missing or are given as -1, the lowest/highest available numbers are used.
Returns: >=0: Number of exported articles, -1: Unknown group; -9: Error
HamArtExportFile( "articles.mbox", "internal.misc" )
HamArtDeleteMid( <message-id> )
Locates the article identified by the given <message-id> and deletes it in Hamster's database-files. The function returns 0, if article could be located and deleted; a value other than 0 otherwise.
Returns: =0: Deleted, <>0: Message-ID not found/deletion failed
HamArtDeleteMid( "<12345.67890@abd.def.ghi>" )
HamArtLocateMid( <message-id>,
<grpname>, <artno> )
HamArtLocateMid( <message-id> )
Returns 0, if the given Message-ID is (still) saved in the history-file. In this case, the variables <grpname> and <artno> will be set to point to this article. Otherwise the function returns a value other than 0 and <grpname> and <artno> remain unchanged.
Returns: =0: OK/found, <>0: Message-ID not found
if( HamArtLocateMid( "<12345.67890@abd.def.ghi>", $groupname, $artno ) ) # ... endif