This is Info file pm.info, produced by Makeinfo version 1.68 from the
input file bigpm.texi.
File: pm.info, Node: WebFetch/COLA, Next: WebFetch/DebianNews, Prev: WebFetch/CNNsearch, Up: Module List
news from the comp.os.linux.announce ("cola") newsgroup
*******************************************************
NAME
====
WebFetch::COLA - news from the comp.os.linux.announce ("cola") newsgroup
SYNOPSIS
========
In perl scripts:
`use WebFetch::COLA;'
From the command line:
`perl -w -MWebFetch::COLA -e "&fetch_main" -- --dir directory
[--noshuffle]'
DESCRIPTION
===========
This module downloads news from the comp.os.linux.announce ("c.o.l.a")
moderator's archive.
After this runs, the file `cola.html' will be created or replaced. If
there already was an `cola.html' file, it will be moved to `Ocola.html'.
The c.o.l.a archive is bursty, with many news items showing up at once,
but only updated every few days. In order to present many current items,
WebFetch::COLA sorts by date but shuffles items which are listed as being
on the same date. The webmaster is advised to include a link to the COLA
archive near the headline list so readers can peruse it if anything listed
gets their attention.
If the shuffle feature is not desired, use the "-noshuffle" command-line
option to disable it.
AUTHOR
======
WebFetch was written by Ian Kluft for the Silicon Valley Linux User
Group (SVLUG). Send patches, bug reports, suggestions and questions to
`maint@webfetch.org'.
SEE ALSO
========
File: pm.info, Node: WebFetch/DebianNews, Next: WebFetch/Freshmeat, Prev: WebFetch/COLA, Up: Module List
download and save Debian News headlines
***************************************
NAME
====
WebFetch::DebianNews - download and save Debian News headlines
SYNOPSIS
========
In perl scripts:
`use WebFetch::DebianNews'
>From the command line:
`perl -w -MWebFetch::DebianNews -e "&fetch_main" -- --dir directory'
DESCRIPTION
===========
This module gets the current headlines from the Debian Linux
organization.
After this runs, the file `debiannews.html' will be created or replaced.
If there already was an `debiannews.html' file, it will be moved to
`Odebiannews.html'.
AUTHOR
======
WebFetch was written by Ian Kluft for the Silicon Valley Linux User
Group (SVLUG). The WebFetch::DebianNews module was written by Chuck
Ritter. Send patches or maintenance requests for this module to
`critter@roadport.com'. Send general patches, bug reports, suggestions
and questions to `maint@webfetch.org'.
SEE ALSO
========
File: pm.info, Node: WebFetch/Freshmeat, Next: WebFetch/General, Prev: WebFetch/DebianNews, Up: Module List
download and save Freshmeat headlines
*************************************
NAME
====
WebFetch::Freshmeat - download and save Freshmeat headlines
SYNOPSIS
========
In perl scripts:
`use WebFetch::Freshmeat;'
From the command line:
`perl -w -MWebFetch::Freshmeat -e "&fetch_main" -- --dir directory'
DESCRIPTION
===========
This module gets the current headlines from Freshmeat.
After this runs, the file `freshmeat.html' will be created or replaced.
If there already was an `freshmeat.html' file, it will be moved to
`Ofreshmeat.html'.
AUTHOR
======
WebFetch was written by Ian Kluft for the Silicon Valley Linux User
Group (SVLUG). Send patches, bug reports, suggestions and questions to
`maint@webfetch.org'.
SEE ALSO
========
File: pm.info, Node: WebFetch/General, Next: WebFetch/LinuxDevNet, Prev: WebFetch/Freshmeat, Up: Module List
download and save headlines from other WebFetch sites
*****************************************************
NAME
====
WebFetch::General - download and save headlines from other WebFetch
sites
SYNOPSIS
========
In perl scripts:
`use WebFetch::General;'
From the command line:
`perl -w -MWebFetch::General -e "&fetch_main" -- --dir directory
--file output-filename --url source-url [--format format]'
DESCRIPTION
===========
This module gets the current headlines from any WebFetch site that
exports its news with the "WebFetch Export" format. You can do this with
the -export command-line parameter. It works for any WebFetch module that
defines the *export()* function, which includes all the modules that come
packaged with WebFetch.
The webmaster of a remote site only needs to arrange for a cron job to
update a WebFetch Export file, and let others know the URL to reach that
file. (On the exporting site, it is most likely they'll use
WebFetch::SiteNews to export their own news.) Then you can use the
WebFetch::General module to read the remote file and generate and HTML
summary of the news.
After WebFetch::General runs, the file specified in the -file parameter
will be created or replaced. If there already was a file by that name, it
will be moved to a filename with "O" (for old) prepended to the file name.
FORMAT STRINGS
==============
WebFetch::General uses a format string to generate HTML from the
incoming data. The default format for retrieved data is
%title%
This means that fields named "url" and "title" must exist in the
incoming WebFetch-exported data, and will be used to fill in the *%url%*
and *%title%* strings, respectively. You may use the -format parameter to
specify any format you wish. But the field names you choose in the format
must match fields defined in the input stream. Otherwise they will fail
to be expanded.
THE "WebFetch Export" FILE FORMAT
=================================
This is an example WebFetch Export file generated by WebFetch::SiteNews:
[WebFetch export]
Version: 0.09
# This was generated by the Perl5 WebFetch 0.09 module.
# WebFetch info can be found at http://www.webfetch.org/
#
# Exported from WebFetch::SiteNews
# "date" is the date of the news
# "title" is a one-liner title
# "url" is url to the news source
# "text" is the news text
date: August 15, 1999
title: WebFetch 0.09 released
url: http://www.webfetch.org/news.shtml#19990815-000
text: WebFetch 0.09 beta adds\
a new LinuxTelephony module, contributed by Greg Youngblood\
as well as modules for Linux Dev.Net, 32BitsOnline\
and other updates
date: August 1, 1999
title: WebFetch 0.08 released
url: http://www.webfetch.org/news.shtml#19990801-000
text: WebFetch 0.08 beta\
adds a new DebianNews module contributed by Chuck Ritter,\
as well as other updates
date: August 1, 1999
title: Slashdot lists Webfetch first among headlines tools
url: http://www.webfetch.org/news.shtml#19990801-001
text: Many thanks to Slashdot\
for listing WebFetch first among the\
tools that can\
display headlines from their site.
Each news item is separated by a blank line.
Within each news item, the fields use a "name: value" format, similar
to RFC822 headers (i.e. as in e-mail and news.)
The names of the fields are chosen by the exporting module. Though for
the convenience of the user, the author of an exporting module should keep
in mind the default WebFetch::General format uses fields called "url" and
"title". If you use fields by different names, warn your receiving users
that they will need to make a format to use with WebFetch::General, though
you may provide them with one in their setup instructions.
AUTHOR
======
WebFetch was written by Ian Kluft for the Silicon Valley Linux User
Group (SVLUG). Send patches, bug reports, suggestions and questions to
`maint@webfetch.org'.
SEE ALSO
========
File: pm.info, Node: WebFetch/LinuxDevNet, Next: WebFetch/LinuxTelephony, Prev: WebFetch/General, Up: Module List
download and save Linux Dev.Net headlines
*****************************************
NAME
====
WebFetch::LinuxDevNet - download and save Linux Dev.Net headlines
SYNOPSIS
========
In perl scripts:
`use WebFetch::LinuxDevNet;'
From the command line:
`perl -w -MWebFetch::LinuxDevNet -e "&fetch_main" -- --dir directory'
DESCRIPTION
===========
This module gets the current headlines from Linux Dev.Net
(linuxdev.net).
After this runs, the file `linuxdevnet.html' will be created or
replaced. If there already was an `linuxdevnet.html' file, it will be
moved to `Olinuxdevnet.html'.
AUTHOR
======
WebFetch was written by Ian Kluft for the Silicon Valley Linux User
Group (SVLUG). Send patches, bug reports, suggestions and questions to
`maint@webfetch.org'.
SEE ALSO
========
File: pm.info, Node: WebFetch/LinuxTelephony, Next: WebFetch/LinuxToday, Prev: WebFetch/LinuxDevNet, Up: Module List
download and save LinuxTelephony headlines
******************************************
NAME
====
WebFetch::LinuxTelephony - download and save LinuxTelephony headlines
SYNOPSIS
========
In perl scripts:
`use WebFetch::LinuxTelephony;'
>From the command line:
`perl -w -MWebFetch::LinuxTelephony -e "&fetch_main" -- --dir directory'
DESCRIPTION
===========
This module gets the current headlines from LinuxTelephony.
After this runs, the file `linuxtelephony.html' will be created or
replaced. If there already was an `linuxtelephony.html' file, it will be
moved to `Olinuxtelephony.html'.
AUTHOR
======
WebFetch was written by Ian Kluft for the Silicon Valley Linux User
Group (SVLUG). Send patches, bug reports, suggestions and questions to
`maint@webfetch.org'.
WebFetch::LinuxTelephony is based on WebFetch::LinuxToday.
Modifications made for WebFetch::LinuxTelephony by Gregory S. Youngblood,
`greg@tcscs.com'.
SEE ALSO
========
File: pm.info, Node: WebFetch/LinuxToday, Next: WebFetch/ListSubs, Prev: WebFetch/LinuxTelephony, Up: Module List
download and save LinuxToday headlines
**************************************
NAME
====
WebFetch::LinuxToday - download and save LinuxToday headlines
SYNOPSIS
========
In perl scripts:
`use WebFetch::LinuxToday;'
From the command line:
`perl -w -MWebFetch::LinuxToday -e "&fetch_main" -- --dir directory'
DESCRIPTION
===========
This module gets the current headlines from LinuxToday.
After this runs, the file `linuxtoday.html' will be created or replaced.
If there already was an `linuxtoday.html' file, it will be moved to
`Olinuxtoday.html'.
AUTHOR
======
WebFetch was written by Ian Kluft for the Silicon Valley Linux User
Group (SVLUG). Send patches, bug reports, suggestions and questions to
`maint@webfetch.org'.
SEE ALSO
========
File: pm.info, Node: WebFetch/ListSubs, Next: WebFetch/PerlStruct, Prev: WebFetch/LinuxToday, Up: Module List
summarize mail list subscriptions
*********************************
NAME
====
WebFetch::ListSubs - summarize mail list subscriptions
SYNOPSIS
========
In perl scripts:
`use WebFetch::ListSubs;'
From the command line:
`perl -w -MWebFetch::ListSubs -e "&fetch_main" -- --dir directory
--list mail-list-file --out output-file [--title table-title]'
DESCRIPTION
===========
This module gets the current subscriptions from a mail list file (used
by a mail list server on the same machine) and summarizes the
subscriptions by top-level domain. The mail list file is in a format used
by Majordomo, SmartList, Smail, Exim and many others - one address per
line. Comments (beginning with "#") and blank lines are allowed but
ignored.
The contents of the mail list are read from the file named in the
`--list' parameter. The summary as an HTML table is written to the file
named by the `--out' parameter. The optional `--title' parameter may be
used to put a title on the HTML table produced by this fetch operation.
AUTHOR
======
WebFetch was written by Ian Kluft for the Silicon Valley Linux User
Group (SVLUG). Send patches, bug reports, suggestions and questions to
`maint@webfetch.org'.
SEE ALSO
========
File: pm.info, Node: WebFetch/PerlStruct, Next: WebFetch/SiteNews, Prev: WebFetch/ListSubs, Up: Module List
accepts a Perl structure with pre-parsed news
*********************************************
NAME
====
WebFetch::PerlStruct - accepts a Perl structure with pre-parsed news
SYNOPSIS
========
In perl scripts:
`use WebFetch::PerlStruct;'
`$obj = new WebFetch::PerlStruct ( "content" =' content_struct, "dir"
=> output_dir, "file" => output_file, [ "format" =>
format_string, ] [ "export" => wf_export_filename, ] [ "ns_export" =>
ns_export_filename, ] [ "ns_export" => ns_export_filename, ] [
"ns_export" => ns_export_filename, ] [ "ns_site_title" =>
ns_export_site_title, ] [ "ns_site_link" => ns_export_site_link, ]
[ "ns_site_desc" => ns_export_site_desc, ] [ "ns_image_title" =>
ns_export_image_title, ] [ "ns_image_url" => ns_export_image_url, ]
[ "font_size" => font_size, ] [ "font_face" => font_face, ] [
"group" => file_group_id, ] [ "mode" => file_mode_perms, ] [
"quiet" => 1 ]);>
*Note: WebFetch::PerlStruct is a Perl interface only. It does not
support usage from the command-line.*
DESCRIPTION
===========
This module accepts a perl structure with pre-parsed news and pushes it
into the WebFetch infrastructure.
The webmaster of a remote site only needs to arrange for a cron job to
update a WebFetch Export file, and let others know the URL to reach that
file. (On the exporting site, it is most likely they'll use
WebFetch::SiteNews to export their own news.) Then you can use the
WebFetch::PerlStruct module to read the remote file and generate and HTML
summary of the news.
After WebFetch::PerlStruct runs, the file specified in the -file
parameter will be created or replaced. If there already was a file by
that name, it will be moved to a filename with "O" (for old) prepended to
the file name.
Most of the parameters listed are inherited from WebFetch. See the
WebFetch module documentation for details.
THE CONTENT STRUCTURE
=====================
The $content_struct parameter must be a reference to an array of hashes.
Each of the hashes represents a separate news item, in the order they
should be displayed. The fields of each has entry must provide enough
information to match field names in all the the output formats you're
using. Output formats include the following:
HTML output file
All the fields used in the $format_string (see below) must be present
for generation of the HTML output.
WebFetch export
The $format_string also determines the fields that will be used for
WebFetch export. Note that the WebFetch::General module expects by
default to find fields called "url" and "title". So if you use
something different from the default, you must provide your format
string in the instructions for sites that fetch news from you.
(Otherwise their WebFetch::General won't be looking for the fields
you're providing.)
MyNetscape export
The MyNetscape export function expects to find fields called "title"
and "url", and will skip any hash entry which is missing either of
them.
FORMAT STRINGS
==============
WebFetch::PerlStruct uses a format string identical to
WebFetch::General. The default format for retrieved data is
%title%
See the WebFetch::General documentation for more details.
The names of the fields are chosen by the calling function. Though for
the convenience of the user, the author of an exporting module should keep
in mind the default WebFetch::PerlStruct format uses fields called "url"
and "title". If you use fields by different names, make sure your code
provides those fields in the $content_struct parameter.
AUTHOR
======
WebFetch was written by Ian Kluft for the Silicon Valley Linux User
Group (SVLUG). Send patches, bug reports, suggestions and questions to
`maint@webfetch.org'.
SEE ALSO
========
File: pm.info, Node: WebFetch/SiteNews, Next: WebFetch/Slashdot, Prev: WebFetch/PerlStruct, Up: Module List
download and save SiteNews headlines
************************************
NAME
====
WebFetch::SiteNews - download and save SiteNews headlines
SYNOPSIS
========
In perl scripts:
`use WebFetch::SiteNews;'
From the command line:
`perl -w -MWebFetch::SiteNews -e "&fetch_main" -- --dir directory
--input news-file --short short-form-output-file --long
long-form-output-file'
DESCRIPTION
===========
This module gets the current headlines from a site-local file.
The *-input* parameter specifies a file name which contains news to be
posted. See `"FILE FORMAT"' in this node below for details on contents to
put in the file. *-input* may be specified more than once, allowing a
single news output to come from more than one input. For example, one
file could be manually maintained in CVS or RCS and another could be
entered from a web form.
After this runs, the file `site_news.html' will be created or replaced.
If there already was a `site_news.html' file, it will be moved to
`Osite_news.html'.
FILE FORMAT
===========
The WebFetch::SiteNews data format is used to set up news for the local
web site and allow other sites to import it via WebFetch. The file is
plain text containing comments and the news items.
There are three forms of outputs generated from these news files.
The *"short news" output* is a small number (5 by default) of HTML text
and links used for display in a small news window. And example of this
can be seen in the "SVLUG News" box on SVLUG's home page. This list takes
into account expiration dates and priorities to pick which news entries
are displayed and in what order.
The *"long news" output* lists all the news entries chronologically.
It does not take expiration or priority into account. It is intended for
a comprehensive site news list. An example can be found on SVLUG's news
page.
The *export modes* make news items available in formats other web sites
can retrieve to post news about your site. They are chronological
listings that omit expired items. They do not take priorities into
account.
global parameters
Lines coming before the first news item can set global parameters.
categories
A line before the first news item beginning with "categories:"
contains a whitespace-delimited list of news category names in
order from highest to lowest priority. These priority names are
used by the news item attributes and then for sorting "short
news" list items.
url-prefix
A global parameter line beginning with "url-prefix:" will
override the -url_prefix command line parameter with a URL
prefix to use when exporting news items via the WebFetch Export
format (see -export) or by MyNetscape's RDF export format (via
-ns_export).
data lines
Non-blank non-indented non-comment lines are *data lines*. Each data
line contains a *name=value* pair. Each group of consecutive data
lines is followed by an arbitrary number of indented lines which
contain HTML text for the news entry.
The recognized attributes are as follows:
category
used for prioritization, values are set by the categories global
parameter (required)
posted
date posted, format is a numerical date YYYYMMDD (required)
expires
expiration date, format is a numerical date YYYYMMDD (optional)
title
shorter title for use in news exports to other sites, otherwise
the whole news text will be used (optional)
text lines
Intended lines are HTML text for the news item.
comments
Comments are lines beginning with "#". They are ignored so they can
be used for human-readable information.
Note that the "short news" list has some modifications to priorities
based on the age of the news item, so that the short list will favor newer
items when they're the same priority. There is a sorting "priority bonus"
for items less than a day old, which increases their priority by two
priority levels. Day-old news items get a bonus of one priority level.
All news items also "decay" in priority slightly every day, dropping a
whole priority level every 40 days.
AUTHOR
======
WebFetch was written by Ian Kluft for the Silicon Valley Linux User
Group (SVLUG). Send patches, bug reports, suggestions and questions to
`maint@webfetch.org'.
SEE ALSO
========
File: pm.info, Node: WebFetch/Slashdot, Next: WebFetch/YahooBiz, Prev: WebFetch/SiteNews, Up: Module List
download and save Slashdot (or any Slashdot-compatible) headlines
*****************************************************************
NAME
====
WebFetch::Slashdot - download and save Slashdot (or any
Slashdot-compatible) headlines
SYNOPSIS
========
In perl scripts:
`use WebFetch::Slashdot;'
From the command line:
`perl -w -MWebFetch::Slashdot -e "&fetch_main" -- --dir directory
[--alt_url url [--alt_file file]'
Alternative command line to filter out specific authors:
`perl -w -MWebFetch::Slashdot -e "&fetch_main" -- --dir directory
--filter author [--alt_url url] [--alt_file file]'
DESCRIPTION
===========
This module gets the current headlines from Slashdot.org via their XML
interface.
The optional `--alt_url' parameter allows you to select a different URL
to get the headlines from.
An optional command-line argument of `--filter' may be used to filter
out specific authors. This is not necessarily recommended but it was in
use at SVLUG when this module was first developed.
After this runs, by default the file `sdot.html' will be created or
replaced. If there already was an `sdot.html' file, it will be moved to
`Osdot.html'. These filenames can be overridden by the `--alt_file'
parameter.
AUTHOR
======
WebFetch was written by Ian Kluft for the Silicon Valley Linux User
Group (SVLUG). Send patches, bug reports, suggestions and questions to
`maint@webfetch.org'.
SEE ALSO
========
File: pm.info, Node: WebFetch/YahooBiz, Next: Wharf/JDockApp, Prev: WebFetch/Slashdot, Up: Module List
download and save YahooBiz headlines
************************************
NAME
====
WebFetch::YahooBiz - download and save YahooBiz headlines
SYNOPSIS
========
In perl scripts:
`use WebFetch::YahooBiz;'
From the command line:
`perl -w -MWebFetch::YahooBiz -e "&fetch_main" -- --dir directory
--search search-string --days search-days --pagesize search-page-size'
DESCRIPTION
===========
This module gets the current headlines from Yahoo Business News.
After this runs, the file `yahoo_biz.html' will be created or replaced.
If there already was an `yahoo_biz.html' file, it will be moved to
`Oyahoo_biz.html'.
AUTHOR
======
WebFetch was written by Ian Kluft for the Silicon Valley Linux User
Group (SVLUG). Send patches, bug reports, suggestions and questions to
`maint@webfetch.org'.
SEE ALSO
========
File: pm.info, Node: Wharf/JDockApp, Next: Wharf/JDockApp/jtools, Prev: WebFetch/YahooBiz, Up: Module List
Perl extension for doing Wharf or Window Maker dockapps.
********************************************************
NAME
====
JDockApp - Perl extension for doing Wharf or Window Maker dockapps.
SYNOPSIS
========
use Wharf::JDockApp;
SetSetup( \&some_func);
SetExpose(\&some_func);
SetUpdate(\&some_func);
SetButton(\&some_func);
SetDelay($delay)
StartApp;
ClearWindow;
also:
jpprint($x, $y, COLOR, "stuff");
jprint( COLOR, "stuff");
DESCRIPTION
===========
SetSetup - called when the JDockApp starts
SetExpose - called when the JDockApp is uncovered
(it's uncovered when the app starts btw)
SetUpdate - called every $delay seconds
SetButton - called whenever someone clicks the JDockApp
SetDelay - You must give this function a number of
seconds--or an Illithid will eat your brain.
When all your /Sets[SEB]/ are set, call StartApp.
ClearWindow - This is a secret function. Only use it
if you are in the know. I'll not
be held responsible if your dockapp
window is clear'd. I simply will not.
Brought with us from Wharf::JDockApp::jtools:
jpprint - print some text at ($x, $y).
jprint - print some text ... starting where we left off.
for both jprint and jpprint, COLOR is a constant
Exported constants
==================
The number of colors for jprintf is quite limited. The reason? The
XPM 'code' is compiled into the binary.
BLUE - the color blue
CYAN - the color cyan
GREEN - the color green
INDIGO - the color indigo
ORANGE - the color orange
PINK - the color pink
RED - the color red
VIOLET - the color violet
YELLOW - the color yellow
EXAMPLES
========
There is an examples directory that comes with the distribution.
In it is a copy of the wmjmail program. It'll parse your mailbox
(rather stupidly) to determin how many messages you have, and
of them how many are new. I couldn't figure out how to get the
Makefile.PL -- without resorting to a total hack -- to install
the wmjmail script. If you can tell me how, please e-mail me
and I'll alter the next distribution.
AUTHOR
======
Jettero Heller
SEE ALSO
========
perl(1), Wharf::JDockApp(3), Wharf::JDockApp::jtools(3).
File: pm.info, Node: Wharf/JDockApp/jtools, Next: Win32, Prev: Wharf/JDockApp, Up: Module List
Perl extension for JDockApp. It's the tools, man.
**************************************************
NAME
====
jtools - Perl extension for JDockApp. It's the tools, man.
SYNOPSIS
========
use Wharf::JDockApp::jtools;
Wharf::JDockApp::jtools::jpprint($x, $y, COLOR, "text");
Wharf::JDockApp::jtools::jprint(COLOR, "text");
Wharf::JDockApp::jtools::set_setup(\&func);
Wharf::JDockApp::jtools::set_expose(\&func);
Wharf::JDockApp::jtools::set_update(\&func);
Wharf::JDockApp::jtools::set_button(\&func);
Wharf::JDockApp::jtools::clear_window;
Wharf::JDockApp::jtools::start_app;
Wharf::JDockApp::jtools::set_update_delay($seconds);
Wharf::JDockApp::jtools::set_loop_delay(1000);
DESCRIPTION
===========
You don't want to use this module. It's the support module for JDockApp.
I drain'd these functions and constants out of JDockApp, because I wanted
whatever tools that may come next to be separate from these.
Later there may be some tools for clearing the white grey line,
adding little pictures and buttons, n' doing lines and circles;
but those would come in like Wharf::JDockApp::geom_tools and
Wharf::JDockApp::buttons. These docs are, therefore, basically just
for completeness. Well, and so if you follow the SEE ALSO white
rabbit, you find something worth reading. ;)
Exported constants
==================
The number of colors for jprintf is quite limited. The reason? The
XPM 'code' is compiled into the binary.
BLUE - the color blue
CYAN - the color cyan
GREEN - the color green
INDIGO - the color indigo
ORANGE - the color orange
PINK - the color pink
RED - the color red
VIOLET - the color violet
YELLOW - the color yellow
AUTHOR
======
Jettero Heller
SEE ALSO
========
perl(1), Wharf::JDockApp(3), Wharf::JDockApp::jtools(3).
File: pm.info, Node: Win32, Next: Win32/ADO, Prev: Wharf/JDockApp/jtools, Up: Module List
Interfaces to some Win32 API Functions
**************************************
NAME
====
Win32 - Interfaces to some Win32 API Functions
DESCRIPTION
===========
Perl on Win32 contains several functions to access Win32 APIs. Some are
included in Perl itself (on Win32) and some are only available after
explicitly requesting the Win32 module with:
use Win32;
The builtin functions are marked as [CORE] and the other ones as [EXT]
in the following alphabetical listing. The Win32 module is not part of the
Perl source distribution; it is distributed in the libwin32 bundle of
Win32::* modules on CPAN. The module is already preinstalled in binary
distributions like ActivePerl.
Alphabetical Listing of Win32 Functions
---------------------------------------
Win32::AbortSystemShutdown(MACHINE)
[EXT] Aborts a system shutdown (started by the InitiateSystemShutdown
function) on the specified MACHINE.
Win32::BuildNumber()
[CORE] Returns the ActivePerl build number. This function is only
available in the ActivePerl binary distribution.
Win32::CopyFile(FROM, TO, OVERWRITE)
[CORE] The Win32::CopyFile() function copies an existing file to a new
file. All file information like creation time and file attributes will
be copied to the new file. However it will not copy the security
information. If the destination file already exists it will only be
overwritten when the OVERWRITE parameter is true. But even this will
not overwrite a read-only file; you have to unlink() it first
yourself.
Win32::DomainName()
[CORE] Returns the name of the Microsoft Network domain that the
owner of the current perl process is logged into.
Win32::ExpandEnvironmentStrings(STRING)
[EXT] Takes STRING and replaces all referenced environment variable
names with their defined values. References to environment variables
take the form `%VariableName%'. Case is ignored when looking up the
VariableName in the environment. If the variable is not found then the
original `%VariableName%' text is retained. Has the same effect as
the following:
$string =~ s/%([^%]*)%/$ENV{$1} || "%$1%"/eg
Win32::FormatMessage(ERRORCODE)
[CORE] Converts the supplied Win32 error number (e.g. returned by
Win32::GetLastError()) to a descriptive string. Analogous to the
perror() standard-C library function. Note that $^E used in a string
context has much the same effect.
C:\> perl -e "$^E = 26; print $^E;"
The specified disk or diskette cannot be accessed
Win32::FsType()
[CORE] Returns the name of the filesystem of the currently active
drive (like 'FAT' or 'NTFS'). In list context it returns three values:
(FSTYPE, FLAGS, MAXCOMPLEN). FSTYPE is the filesystem type as before.
FLAGS is a combination of values of the following table:
0x00000001 supports case-sensitive filenames
0x00000002 preserves the case of filenames
0x00000004 supports Unicode in filenames
0x00000008 preserves and enforces ACLs
0x00000010 supports file-based compression
0x00000020 supports disk quotas
0x00000040 supports sparse files
0x00000080 supports reparse points
0x00000100 supports remote storage
0x00008000 is a compressed volume (e.g. DoubleSpace)
0x00010000 supports object identifiers
0x00020000 supports the Encrypted File System (EFS)
MAXCOMPLEN is the maximum length of a filename component (the part
between two backslashes) on this file system.
Win32::FreeLibrary(HANDLE)
[EXT] Unloads a previously loaded dynamic-link library. The HANDLE is
no longer valid after this call. See
`LoadLibrary|Win32::LoadLibrary(LIBNAME)' in this node for
information on dynamically loading a library.
Win32::GetArchName()
[EXT] Use of this function is deprecated. It is equivalent with
$ENV{PROCESSOR_ARCHITECTURE}. This might not work on Win9X.
Win32::GetChipName()
[EXT] Returns the processor type: 386, 486 or 586 for Intel
processors, 21064 for the Alpha chip.
Win32::GetCwd()
[CORE] Returns the current active drive and directory. This function
does not return a UNC path, since the functionality required for such
a feature is not available under Windows 95.
Win32::GetFullPathName(FILENAME)
[CORE] GetFullPathName combines the FILENAME with the current drive
and directory name and returns a fully qualified (aka, absolute) path
name. In list context it returns two elements: (PATH, FILE) where
PATH is the complete pathname component (including trailing backslash)
and FILE is just the filename part. Note that no attempt is made to
convert 8.3 components in the supplied FILENAME to longnames or
vice-versa. Compare with Win32::GetShortPathName and
Win32::GetLongPathName.
This function has been added for Perl 5.6.
Win32::GetLastError()
[CORE] Returns the last error value generated by a call to a Win32 API
function. Note that $^E used in a numeric context amounts to the
same value.
Win32::GetLongPathName(PATHNAME)
[CORE] Returns a representaion of PATHNAME composed of longname
components (if any). The result may not necessarily be longer than
PATHNAME. No attempt is made to convert PATHNAME to the absolute
path. Compare with Win32::GetShortPathName and
Win32::GetFullPathName.
This function has been added for Perl 5.6.
Win32::GetNextAvailDrive()
[CORE] Returns a string in the form of ":" where is the first
available drive letter.
Win32::GetOSVersion()
[CORE] Returns the array (STRING, MAJOR, MINOR, BUILD, ID), where the
elements are, respectively: An arbitrary descriptive string, the
major version number of the operating system, the minor version
number, the build number, and a digit indicating the actual operating
system. For ID, the values are 0 for Win32s, 1 for Windows 9X and 2
for Windows NT. In scalar context it returns just the ID.
Win32::GetShortPathName(PATHNAME)
[CORE] Returns a representation of PATHNAME composed only of short
(8.3) path components. The result may not necessarily be shorter
than PATHNAME. Compare with Win32::GetFullPathName and
Win32::GetLongPathName.
Win32::GetProcAddress(INSTANCE, PROCNAME)
[EXT] Returns the address of a function inside a loaded library. The
information about what you can do with this address has been lost in
the mist of time. Use the Win32::API module instead of this deprecated
function.
Win32::GetTickCount()
[CORE] Returns the number of milliseconds elapsed since the last
system boot. Resolution is limited to system timer ticks (about 10ms
on WinNT and 55ms on Win9X).
Win32::InitiateSystemShutdown(MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT)
[EXT] Shutsdown the specified MACHINE, notifying users with the
supplied MESSAGE, within the specified TIMEOUT interval. Forces
closing of all documents without prompting the user if FORCECLOSE is
true, and reboots the machine if REBOOT is true. This function works
only on WinNT.
Win32::IsWinNT()
[CORE] Returns non zero if the Win32 subsystem is Windows NT.
Win32::IsWin95()
[CORE] Returns non zero if the Win32 subsystem is Windows 95.
Win32::LoadLibrary(LIBNAME)
[EXT] Loads a dynamic link library into memory and returns its module
handle. This handle can be used with Win32::GetProcAddress and
Win32::FreeLibrary. This function is deprecated. Use the Win32::API
module instead.
Win32::LoginName()
[CORE] Returns the username of the owner of the current perl process.
Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE)
[EXT] Looks up ACCOUNT on SYSTEM and returns the domain name the SID
and the SID type.
Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE)
[EXT] Looks up SID on SYSTEM and returns the account name, domain
name, and the SID type.
Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]])
[EXT] Create a dialogbox containing MESSAGE. FLAGS specifies the
required icon and buttons according to the following table:
0 = OK
1 = OK and Cancel
2 = Abort, Retry, and Ignore
3 = Yes, No and Cancel
4 = Yes and No
5 = Retry and Cancel
MB_ICONSTOP "X" in a red circle
MB_ICONQUESTION question mark in a bubble
MB_ICONEXCLAMATION exclamation mark in a yellow triangle
MB_ICONINFORMATION "i" in a bubble
TITLE specifies an optional window title. The default is "Perl".
The function returns the menu id of the selected push button:
0 Error
1 OK
2 Cancel
3 Abort
4 Retry
5 Ignore
6 Yes
7 No
Win32::NodeName()
[CORE] Returns the Microsoft Network node-name of the current machine.
Win32::RegisterServer(LIBRARYNAME)
[EXT] Loads the DLL LIBRARYNAME and calls the function
DllRegisterServer.
Win32::SetCwd(NEWDIRECTORY)
[CORE] Sets the current active drive and directory. This function
does not work with UNC paths, since the functionality required to
required for such a feature is not available under Windows 95.
Win32::SetLastError(ERROR)
[CORE] Sets the value of the last error encountered to ERROR. This is
that value that will be returned by the Win32::GetLastError()
function. This functions has been added for Perl 5.6.
Win32::Sleep(TIME)
[CORE] Pauses for TIME milliseconds. The timeslices are made available
to other processes and threads.
Win32::Spawn(COMMAND, ARGS, PID)
[CORE] Spawns a new process using the supplied COMMAND, passing in
arguments in the string ARGS. The pid of the new process is stored in
PID. This function is deprecated. Please use the Win32::Process module
instead.
Win32::UnregisterServer(LIBRARYNAME)
[EXT] Loads the DLL LIBRARYNAME and calls the function
DllUnregisterServer.
File: pm.info, Node: Win32/ADO, Next: Win32/API, Prev: Win32, Up: Module List
ADO Constants and a couple of helper functions
**********************************************
NAME
====
Win32::ADO - ADO Constants and a couple of helper functions
SYNOPSIS
========
use Win32::ADO qw/CheckDBErrors/;
DESCRIPTION
===========
Not much to say. Simply provides all the ADO constants for your use,
like in VBScript (or JavaScript). This module is really deprecated in
favour of Win32::OLE::Const, and the proper ADO constants. Use that with
the following syntax:
use Win32::OLE::Const;
my $name = "Microsoft ActiveX Data Objects 2\\.0 Library";
$ado_consts = Win32::OLE::Const->Load($name)
|| die "Unable to load Win32::OLE::Const ``$name'' ".Win32::OLE->LastError;
And then use $ado_consts as a hash ref with the keys being the constant
names.
Also contains CheckDBErrors, for doing ADO error checking. Pass it the
connection object and an empty array ref, as follows:
CheckDBErrors($Conn, \@DBErrors) or die @DBErrors;
Have fun...
AUTHOR
======
Matt Sergeant, matt@sergeant.org
File: pm.info, Node: Win32/API, Next: Win32/ASP, Prev: Win32/ADO, Up: Module List
Perl Win32 API Import Facility
******************************
NAME
====
Win32::API - Perl Win32 API Import Facility
SYNOPSIS
========
use Win32::API;
$function = new Win32::API(
$library, $functionname, \@argumenttypes, $returntype,
);
$return = $function->Call(@arguments);
ABSTRACT
========
With this module you can import and call arbitrary functions from
Win32's Dynamic Link Libraries (DLL), without having to write an XS
extension. Note, however, that this module can't do anything (parameters
input and output is limited to simpler cases), and anyway a regular XS
extension is always safer and faster.
The current version of Win32::API is available at my website:
http://dada.perl.it/
It's also available on your nearest CPAN mirror (but allow a few days
for worldwide spreading of the latest version) reachable at:
http://www.perl.com/CPAN/authors/Aldo_Calpini/
A short example of how you can use this module (it just gets the PID of
the current process, eg. same as Perl's internal $$):
use Win32::API;
$GetPID = new Win32::API("kernel32", "GetCurrentProcessId", '', 'N');
$PID = $GetPID->Call();
The possibilities are nearly infinite (but not all are good :-). Enjoy
it.
CREDITS
=======
All the credits go to Andrea Frosini for the neat assembler trick that
makes this thing work. A big thank you also to Gurusamy Sarathy for his
unvaluable help in XS development, and to all the Perl community for being
what it is.
DESCRIPTION
===========
To use this module put the following line at the beginning of your
script:
use Win32::API;
You can now use the new() function of the Win32::API module to create a
new API object (see `IMPORTING A FUNCTION' in this node) and then invoke
the `Call()' method on this object to perform a call to the imported API
(see `CALLING AN IMPORTED FUNCTION' in this node).
IMPORTING A FUNCTION
--------------------
You can import a function from a 32 bit Dynamic Link Library (DLL) file
with the new() function. This will create a Perl object that contains the
reference to that function, which you can later `Call()'. You need to
pass 4 parameters:
1. The name of the library from which you want to import the function.
2. The name of the function (as exported by the library).
3. The number and types of the arguments the function expects as input.
4. The type of the value returned by the function.
To better explain their meaning, let's suppose that we want to
import and call the Win32 API `GetTempPath()'. This function is defined
in C as:
DWORD WINAPI GetTempPathA( DWORD nBufferLength, LPSTR lpBuffer );
This is documented in the *Win32 SDK Reference*; you can look for it on
the Microsoft's WWW site, or in your C compiler's documentation, if you
own one.
1. The first parameter is the name of the library file that exports this
function; our function resides in the `KERNEL32.DLL' system file.
When specifying this name as parameter, the `.DLL' extension is
implicit, and if no path is given, the file is searched through a
couple of directories, including:
1. The directory from which the application loaded.
2. The current directory.
3. The Windows system directory (eg. c:\windows\system or system32).
4. The Windows directory (eg. c:\windows).
5. The directories that are listed in the PATH environment variable.
So, you don't have to write `C:\windows\system\kernel32.dll';
only `kernel32' is enough:
$GetTempPath = new Win32::API('kernel32', ...
2. Now for the second parameter: the name of the function. It must be
written exactly as it is exported by the library (case is significant
here). If you are using Windows 95 or NT 4.0, you can use the *Quick
View* command on the DLL file to see the function it exports.
Remember that you can only import functions from 32 bit DLLs: in
Quick View, the file's characteristics should report somewhere "32
bit word machine"; as a rule of thumb, when you see that all the
exported functions are in upper case, the DLL is a 16 bit one and you
can't use it. If their capitalization looks correct, then it's
probably a 32 bit DLL.
Also note that many Win32 APIs are exported twice, with the addition
of a final A or W to their name, for - respectively - the ASCII and
the Unicode version. When a function name is not found, Win32::API
will actually append an A to the name and try again; if the extension
is built on a Unicode system, then it will try with the W instead.
So our function name will be:
$GetTempPath = new Win32::API('kernel32', 'GetTempPath', ...
In our case `GetTempPath' is really loaded as `GetTempPathA'.
3. The third parameter, the input parameter list, specifies how many
arguments the function wants, and their types. It can be passed as a
single string, in which each character represents one parameter, or
as a list reference. The following forms are valid:
"abcd"
[a, b, c, d]
\@LIST
But those are not:
(a, b, c, d)
@LIST
The number of characters, or elements in the list, specifies the
number of parameters, and each character or element specifies the
type of an argument; allowed types are:
I: value is an integer
N: value is a number (long)
F: value is a floating point number (float)
D: value is a double precision number (double)
P: value is a pointer (to a string, structure, etc...)
Our function needs two parameters: a number (`DWORD') and a pointer
to a string (`LPSTR'):
$GetTempPath = new Win32::API('kernel32', 'GetTempPath', 'NP', ...
4. The fourth and final parameter is the type of the value returned by
the function. It can be one of the types seen above, plus another
type named V (for void), used for functions that do not return a
value. In our example the value returned by GetTempPath() is a
`DWORD', so our return type will be N:
$GetTempPath = new Win32::API('kernel32', 'GetTempPath', 'NP', 'N');
Now the line is complete, and the GetTempPath() API is ready to be
used in Perl. Before calling it, you should test that $GetTempPath is
defined, otherwise either the function or the library could not be
loaded; in this case, $! will be set to the error message reported by
Windows. Our definition, with error checking added, should then look
like this:
$GetTempPath = new Win32::API('kernel32', 'GetTempPath', 'NP', 'N');
if(not defined $GetTempPath) {
die "Can't import API GetTempPath: $!\n";
}
CALLING AN IMPORTED FUNCTION
----------------------------
To effectively make a call to an imported function you must use the
Call() method on the Win32::API object you created. Continuing with the
example from the previous paragraph, the GetTempPath() API can be called
using the method:
$GetTempPath->Call(...
Of course, parameters have to be passed as defined in the import phase.
In particular, if the number of parameters does not match (in the example,
if GetTempPath() is called with more or less than two parameters), Perl
will croak an error message and die.
The two parameters needed here are the length of the buffer that will
hold the returned temporary path, and a pointer to the buffer itself. For
numerical parameters, you can use either a constant expression or a
variable, while *for pointers you must use a variable name* (no Perl
references, just a plain variable name). Also note that *memory must be
allocated before calling the function*, just like in C. For example, to
pass a buffer of 80 characters to GetTempPath(), it must be initialized
before with:
$lpBuffer = " " x 80;
This allocates a string of 80 characters. If you don't do so, you'll
probably get `Runtime exception' errors, and generally nothing will work.
The call should therefore include:
$lpBuffer = " " x 80;
$GetTempPath->Call(80, $lpBuffer);
And the result will be stored in the $lpBuffer variable. Note that you
don't need to pass a reference to the variable (eg. you *don't need*
`\$lpBuffer'), even if its value will be set by the function.
A little problem here is that Perl does not trim the variable, so
$lpBuffer will still contain 80 characters in return; the exceeding
characters will be spaces, because we said `" " x 80'.
In this case we're lucky enough, because the value returned by the
GetTempPath() function is the length of the string, so to get the actual
temporary path we can write:
$lpBuffer = " " x 80;
$return = $GetTempPath->Call(80, $lpBuffer);
$TempPath = substr($lpBuffer, 0, $return);
If you don't know the length of the string, you can usually cut it at
the `\0' (ASCII zero) character, which is the string delimiter in C:
$TempPath = ((split(/\0/, $lpBuffer))[0];
# or
$lpBuffer =~ s/\0.*$//;
Another note: to pass a pointer to a structure in C, you have to pack()
the required elements in a variable. And of course, to access the values
stored in a structure, unpack() it as required. A short example of how it
works: the `POINT' structure is defined in C as:
typedef struct {
LONG x;
LONG y;
} POINT;
Thus, to call a function that uses a `POINT' structure you need the
following lines:
$GetCursorPos = new Win32::API('user32', 'GetCursorPos', 'P', 'V');
$lpPoint = pack('LL', 0, 0); # store two LONGs
$GetCursorPos->Call($lpPoint);
($x, $y) = unpack('LL', $lpPoint); # get the actual values
The rest is left as an exercise to the reader...
AUTHOR
======
Aldo Calpini ( *dada@perl.it* ).
File: pm.info, Node: Win32/ASP, Next: Win32/ASP/DBRecord, Prev: Win32/API, Up: Module List
a Module for ASP (PerlScript) Programming
*****************************************
NAME
====
Win32::ASP - a Module for ASP (PerlScript) Programming
SYNOPSIS
========
use Win32::ASP;
print "This is a test
";
$PageName = GetFormValue('PageName');
if($PageName eq 'Select a page...') {
die "Please go back and select a value from the Pages list";
}
print "You selected the ", $PageName, " page";
exit;
DESCRIPTION
===========
These routines are some I knocked together one day when I was saying the
following: "Why don't my "print" statements output to the browser?" and
"Why doesn't exit and die end my script?". So I started investigating how
I could overload the core functions. "print" is overloaded via the tie
mechanism (thanks to Eryq (`eryq@zeegee.com'), Zero G Inc. for the code
which I ripped from IO::Scalar). You can also get at print using the OO
mechanism with $Win32::ASP::SH->print(). Also added recently was code that
allowed cleanup stuff to be executed when you exit() or die(), this comes
in the form of the `AddDeathHook' function. The `BinaryWrite' function
simply wraps up unicode conversion and BinaryWrite in one call. Finally I
was annoyed that I couldn't just develop a script using GET and then
change to POST for release because of the difference in how the ASP code
handles the different formats, GetFormValue solves that one.
Installation instructions
-------------------------
Usually ActiveState are pretty "on the ball" with CPAN archives, so it
should just be a matter of typing:
ppm install Win32-ASP
on the command line. Make sure you're connected to the internet first.
Function Reference
==================
Print LIST
----------
Prints a string or comma separated list of strings to the browser. Use
as if you were using print in a CGI application. Print gets around ASP's
limitations of 128k in a single Response->Write call.
Obsolete - use print instead.
NB: print calls Print, so you could use either, but print is more
integrated with "the perl way".
DebugPrint LIST
---------------
The same as Print except the output is between HTML comments so that
you can only see it with "view source". DebugPrint is not exported so you
have to use it as Win32::ASP::DebugPrint()
This function is useful to debug your application. For example I use it
to print out SQL before it is executed.
HTMLPrint LIST
--------------
The same as Print except the output is taken and encoded so that any
html tags appear as sent, i.e. < becomes <, > becomes > etc.
HTMLPrint is not exported, so use it like Win32::ASP::HTMLPrint.
This function is useful for printing output that comes from a database
or a file, where you don't have total control over the input.
wprint LIST
-----------
Obsolete: Use Print instead
die LIST
--------
Prints the contents of LIST to the browser and then exits. die
automatically calls $Response->End for you, it also executes any cleanup
code you have added with `AddDeathHook'.
exit
----
Exits the current script. $Response->End is called automatically for
you, and any cleanup code added with `AddDeathHook' is also called.
HTMLEncode LIST
---------------
The same as HTMLPrint except the output is not printed but returned as
a scalar instead. HTMLEncode is not exported, so use it like
Win32::ASP::HTMLEncode.
This function is useful to handle output that comes from a database or
a file, where you don't have total control over the input.
If an array ref is passed it uses the ref, otherwise it assumes an
array of scalars is used. Using a ref makes for less time spent passing
values back and forth, and is the prefered method.
GetFormValue EXPR [, EXPR]
--------------------------
returns the value passed from a form (or non-form GET request). Use this
method if you want to be able to develop in GET mode (for ease of
debugging) and move to POST mode for release. The second (optional)
parameter is for getting multiple parameters as in:
http://localhost/scripts/test.asp?Q=a&Q=b
In the above GetFormValue("Q", 1) returns "a" and GetFormValue("Q", 2)
returns "b".
GetFormValue will work in an array context too, returning all the values
for a particular parameter. For example with the above url:
my @AllQs = GetFormValue('Q');
will return an array: @AllQs = ('a', 'b')
Also just added: If you call GetFormValue without any parameters it will
return a list of Form parameters in the same way that CGI.pm's param()
function does. This allows easy iteration over the form elements:
foreach my $key (GetFormValue()) {
print "$key = ", GetFormValue($key), "
\n";
}
Also added a param() function which works exactly as GetFormValue does,
for compatibility with CGI.pm.
GetFormCount EXPR
-----------------
returns the number of times EXPR appears in the request (Form or
QueryString). Use this value as $i to iterate over GetFormValue(EXPR, $i).
For example, url is:
http://localhost/scripts/myscript.asp?Q=a&Q=b
And code is:
my $numQs = GetFormCount('Q');
gives $numQs = 2
AddDeathHook LIST
-----------------
This frightening sounding function allows you to have cleanup code
executed when you die or exit. For example you may want to disconnect from
your database if there is a problem:
<%
my $Conn = $Server->CreateObject('ADODB.Connection');
$Conn->Open( "DSN=BADEV1;UID=sa;DATABASE=ProjAlloc" );
$Conn->BeginTrans();
Win32::ASP::AddDeathHook( sub { $Conn->Close if $Conn; } );
%>
Now when you die because of an error, your database connection will
close gracefully, instead of you having loads of rogue connections that
you have to kill by hand, or restart your database once a day.
Death hooks should be executed on a graceful exit of the script too,
but I've been unable to confirm this. If anyone has any luck, let me know.
BinaryWrite LIST
----------------
Performs the same function as `$Response->'`BinaryWrite()' but gets
around Perl's lack of unicode support, and the null padding it uses to get
around this.
Example:
Win32::ASP::BinaryWrite($val);
SetCookie Name, Value [, HASH]
------------------------------
Sets the cookie Name with the value Value. HASH is option, and contains
any of the following optional parameters:
* -expires => A CGI.pm style expires value (see the CGI.pm docs for
header() for this).
* -domain => a domain in the style ".matt.com" that the cookie is
returned to.
* -path => a path that the cookie is returned to.
* -secure => cookie only gets returned under SSL if this is true.
If Value is a hash ref, then it creates a cookie dictionary. (see either
the ASP docs, or my Introduction to PerlScript for more info on Cookie
Dictionaries).
Example:
Win32::ASP::SetCookie("Matt", "Sergeant", ( -expires => "+3h",
-domain => ".matt.com",
-path => "/users/matt",
-secure => 0 ));
Experimental STDIN support
==========================
Version 2.10 adds experimental support for STDIN processing. You should
be able to go `while( now. However, I don't have an NT
machine to test this on (I dumped NT in favour of Linux a while back), so
it's caveat emptor - and feed me with bug reports if you want it to work.
The idea is that now CGI.pm should be able to read form data and file
uploads appropriately. If it works, let me know. If it doesn't, let me
know too :)