summaryrefslogtreecommitdiff
path: root/source4
diff options
context:
space:
mode:
authorJelmer Vernooij <jelmer@samba.org>2005-10-08 00:33:19 +0000
committerGerald (Jerry) Carter <jerry@samba.org>2007-10-10 13:39:33 -0500
commit848dff8f0d9242c0c7a417a1482c14ac289deb6f (patch)
tree25019d0267b46b577aec10b4a7d2c8769e7239fb /source4
parentb1b6eb7b67542c656e1c087ba590c4269f867772 (diff)
downloadsamba-848dff8f0d9242c0c7a417a1482c14ac289deb6f.tar.gz
samba-848dff8f0d9242c0c7a417a1482c14ac289deb6f.tar.bz2
samba-848dff8f0d9242c0c7a417a1482c14ac289deb6f.zip
r10829: Documentation updates
Update TODO Some small fixes to the modules (This used to be commit 0c53e7c3cf7fd91fd34c48a5e68c1bcf70569854)
Diffstat (limited to 'source4')
-rw-r--r--source4/pidl/TODO13
-rw-r--r--source4/pidl/lib/Parse/Pidl/Dump.pm14
-rw-r--r--source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm75
-rw-r--r--source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm8
-rw-r--r--source4/pidl/lib/Parse/Pidl/NDR.pm32
-rw-r--r--source4/pidl/lib/Parse/Pidl/Samba3/Header.pm15
-rw-r--r--source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm40
-rwxr-xr-xsource4/pidl/pidl83
8 files changed, 180 insertions, 100 deletions
diff --git a/source4/pidl/TODO b/source4/pidl/TODO
index 9fc3a7d904..ca5047c0d7 100644
--- a/source4/pidl/TODO
+++ b/source4/pidl/TODO
@@ -1,16 +1,17 @@
-- True multiple dimension array / strings in arrays support
+- true multiple dimension array / strings in arrays support
- compatibility mode for generating MIDL-readable data:
- strip out pidl-specific properties
- - convert subcontext() to an array of uint8.
- - perhaps replace subcontext() with something more generic? The argument
- to subcontext() isn't really intuitive at the moment
- don't be so strict on array boundaries.. arrays can and will be empty when
a (regular) remote error occurs
- support nested elements
-- Don't output [ref] pointers for Samba 4?
+- auto-alloc [ref] pointers for Samba4 during pull if they were NULL
-- alternative to subcontext()
+- better replacement for subcontext()
+
+- --explain-ndr option that dumps out parse tree
+
+- fix test suite
diff --git a/source4/pidl/lib/Parse/Pidl/Dump.pm b/source4/pidl/lib/Parse/Pidl/Dump.pm
index 80219a8f1a..3a1cec1b59 100644
--- a/source4/pidl/lib/Parse/Pidl/Dump.pm
+++ b/source4/pidl/lib/Parse/Pidl/Dump.pm
@@ -1,8 +1,22 @@
###################################################
# dump function for IDL structures
# Copyright tridge@samba.org 2000
+# Copyright jelmer@samba.org 2005
# released under the GNU GPL
+=pod
+
+=head1 NAME
+
+Parse::Pidl::Dump - Dump support
+
+=head1 DESCRIPTION
+
+This module provides functions that can generate IDL code from
+internal pidl data structures.
+
+=cut
+
package Parse::Pidl::Dump;
use Exporter;
diff --git a/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm b/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm
index 706a259306..1b550ae1e7 100644
--- a/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm
+++ b/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm
@@ -3,6 +3,81 @@
# Copyright jelmer@samba.org 2005
# released under the GNU GPL
+=pod
+
+=head1 NAME
+
+Parse::Pidl::Ethereal::Conformance - Conformance file parser for Ethereal
+
+=head1 DESCRIPTION
+
+This module supports parsing Ethereal conformance files (*.cnf).
+
+=head1 FILE FORMAT
+
+Pidl needs additional data for ethereal output. This data is read from
+so-called conformance files. This section describes the format of these
+files.
+
+Conformance files are simple text files with a single command on each line.
+Empty lines and lines starting with a '#' character are ignored.
+Arguments to commands are seperated by spaces.
+
+The following commands are currently supported:
+
+=over 4
+
+=item I<TYPE> name dissector ft_type base_type mask valsstring alignment
+
+Register new data type with specified name, what dissector function to call
+and what properties to give header fields for elements of this type.
+
+=item I<NOEMIT> type
+
+Suppress emitting a dissect_type function for the specified type
+
+=item I<PARAM_VALUE> type param
+
+Set parameter to specify to dissector function for given type.
+
+=item I<HF_FIELD> hf title filter ft_type base_type valsstring mask description
+
+Generate a custom header field with specified properties.
+
+=item I<HF_RENAME> old_hf_name new_hf_name
+
+Force the use of new_hf_name when the parser generator was going to
+use old_hf_name.
+
+This can be used in conjunction with HF_FIELD in order to make more then
+one element use the same filter name.
+
+=item I<STRIP_PREFIX> prefix
+
+Remove the specified prefix from all function names (if present).
+
+=item I<PROTOCOL> longname shortname filtername
+
+Change the short-, long- and filter-name for the current interface in
+Ethereal.
+
+=item I<FIELD_DESCRIPTION> field desc
+
+Change description for the specified header field. `field' is the hf name of the field.
+
+=item I<IMPORT> dissector code...
+
+Code to insert when generating the specified dissector. @HF@ and
+@PARAM@ will be substituted.
+
+=back
+
+=head1 EXAMPLE
+
+ INFO_KEY OpenKey.Ke
+
+=cut
+
package Parse::Pidl::Ethereal::Conformance;
require Exporter;
diff --git a/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm b/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm
index be542638ef..8a4c0ed60c 100644
--- a/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm
+++ b/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm
@@ -6,6 +6,14 @@
# Portions based on idl2eth.c by Ronnie Sahlberg
# released under the GNU GPL
+=pod
+
+=head1 NAME
+
+Parse::Pidl::Ethereal::NDR - Parser generator for Ethereal
+
+=cut
+
package Parse::Pidl::Ethereal::NDR;
use strict;
diff --git a/source4/pidl/lib/Parse/Pidl/NDR.pm b/source4/pidl/lib/Parse/Pidl/NDR.pm
index 64190e87b8..f975e07b15 100644
--- a/source4/pidl/lib/Parse/Pidl/NDR.pm
+++ b/source4/pidl/lib/Parse/Pidl/NDR.pm
@@ -5,6 +5,26 @@
# Copyright jelmer@samba.org 2004-2005
# released under the GNU GPL
+=pod
+
+=head1 NAME
+
+Parse::Pidl::NDR - NDR parsing information generator
+
+=head1 DESCRIPTION
+
+#####################################################################
+# return a table describing the order in which the parts of an element
+# should be parsed
+# Possible level types:
+# - POINTER
+# - ARRAY
+# - SUBCONTEXT
+# - SWITCH
+# - DATA
+
+=cut
+
package Parse::Pidl::NDR;
require Exporter;
@@ -62,15 +82,6 @@ sub fatal($$)
die("$pos->{FILE}:$pos->{LINE}:$s\n");
}
-#####################################################################
-# return a table describing the order in which the parts of an element
-# should be parsed
-# Possible level types:
-# - POINTER
-# - ARRAY
-# - SUBCONTEXT
-# - SWITCH
-# - DATA
sub GetElementLevelTable($)
{
my $e = shift;
@@ -394,6 +405,7 @@ sub ParseUnion($)
if (has_property($e, "nodiscriminant")) { $switch_type = undef; }
+ my $hasdefault = 0;
foreach my $x (@{$e->{ELEMENTS}})
{
my $t;
@@ -404,6 +416,7 @@ sub ParseUnion($)
}
if (has_property($x, "default")) {
$t->{CASE} = "default";
+ $hasdefault = 1;
} elsif (defined($x->{PROPERTIES}->{case})) {
$t->{CASE} = "case $x->{PROPERTIES}->{case}";
} else {
@@ -417,6 +430,7 @@ sub ParseUnion($)
SWITCH_TYPE => $switch_type,
ELEMENTS => \@elements,
PROPERTIES => $e->{PROPERTIES},
+ HAS_DEFAULT => $hasdefault,
ORIGINAL => $e
};
}
diff --git a/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm b/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm
index 78bd8fe339..25102e511a 100644
--- a/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm
+++ b/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm
@@ -31,7 +31,6 @@ sub ParseElement($)
return if ($l->{POINTER_TYPE} eq "ref" and $l->{LEVEL} eq "top");
pidl "\tuint32 ptr$l->{POINTER_INDEX}_$e->{NAME};";
} elsif ($l->{TYPE} eq "SWITCH") {
- pidl "\tuint32 level_$e->{NAME};";
} elsif ($l->{TYPE} eq "DATA") {
pidl "\t" . DeclShort($e) . ";";
} elsif ($l->{TYPE} eq "ARRAY") {
@@ -106,30 +105,28 @@ sub ParseUnion($$$)
my $extra = {};
- unless (has_property($u, "nodiscriminant")) {
- $extra->{switch_value} = 1;
- }
+ $extra->{switch_value} = $u->{SWITCH_TYPE};
foreach my $e (@{$u->{ELEMENTS}}) {
foreach my $l (@{$e->{LEVELS}}) {
if ($l->{TYPE} eq "ARRAY") {
if ($l->{IS_CONFORMANT}) {
- $extra->{"size"} = 1;
+ $extra->{"size"} = "uint32";
}
if ($l->{IS_VARYING}) {
- $extra->{"length"} = $extra->{"offset"} = 1;
+ $extra->{"length"} = $extra->{"offset"} = "uint32";
}
} elsif ($l->{TYPE} eq "POINTER") {
- $extra->{"ptr$l->{POINTER_INDEX}"} = 1;
+ $extra->{"ptr$l->{POINTER_INDEX}"} = "uint32";
} elsif ($l->{TYPE} eq "SWITCH") {
- $extra->{"level"} = 1;
+ $extra->{"level"} = "uint32";
}
}
}
pidl "typedef struct $if->{NAME}_$n\_ctr {";
indent;
- pidl "uint32 $_;" foreach (keys %$extra);
+ pidl "$extra->{$_} $_;" foreach (keys %$extra);
pidl "union $if->{NAME}_$n {";
indent;
foreach (@{$u->{ELEMENTS}}) {
diff --git a/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm b/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm
index eaab50b553..c6cc188391 100644
--- a/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm
+++ b/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm
@@ -75,8 +75,18 @@ sub ParseElementLevelData($$$$$$$)
# See if we need to add a level argument because we're parsing a union
foreach (@{$e->{LEVELS}}) {
- push (@args, ParseExpr("level_$e->{NAME}", $env))
- if ($_->{TYPE} eq "SWITCH");
+ next unless ($_->{TYPE} eq "SWITCH");
+ my $t = getType($l->{DATA_TYPE});
+
+ # Set 0 here because one of the variables referenced in SWITCH_IS
+ # might be an in variable while this one is [out]
+ if (grep(/in/, @{$e->{DIRECTION}}) or
+ not defined($t) or
+ has_property($t->{DATA}, "nodiscriminant")) {
+ push (@args, ParseExpr($_->{SWITCH_IS}, $env));
+ } else {
+ push (@args, -1);
+ }
}
my $c = DissectType(@args);
@@ -263,7 +273,6 @@ sub GenerateEnvElement($$)
} elsif ($l->{TYPE} eq "POINTER") {
$env->{"ptr$l->{POINTER_INDEX}_$e->{NAME}"} = "v->ptr$l->{POINTER_INDEX}_$e->{NAME}";
} elsif ($l->{TYPE} eq "SWITCH") {
- $env->{"level_$e->{NAME}"} = "v->level_$e->{NAME}";
} elsif ($l->{TYPE} eq "ARRAY") {
$env->{"length_$e->{NAME}"} = "v->length_$e->{NAME}";
$env->{"size_$e->{NAME}"} = "v->size_$e->{NAME}";
@@ -368,7 +377,6 @@ sub UnionGenerateEnvElement($)
} elsif ($l->{TYPE} eq "POINTER") {
$env->{"ptr$l->{POINTER_INDEX}_$e->{NAME}"} = "v->ptr$l->{POINTER_INDEX}";
} elsif ($l->{TYPE} eq "SWITCH") {
- $env->{"level_$e->{NAME}"} = "v->level";
} elsif ($l->{TYPE} eq "ARRAY") {
$env->{"length_$e->{NAME}"} = "v->length";
$env->{"size_$e->{NAME}"} = "v->size";
@@ -394,15 +402,20 @@ sub ParseUnion($$$)
indent;
DeclareArrayVariables($u->{ELEMENTS});
- unless (has_property($u, "nodiscriminant")) {
- pidl "if (!prs_uint32(\"switch_value\", ps, depth, &v->switch_value))";
+ if (defined ($u->{SWITCH_TYPE})) {
+ pidl "if (MARSHALLING(ps)) ";
+ pidl "\tv->switch_value = level;";
+ pidl "";
+ pidl "if (!prs_$u->{SWITCH_TYPE}(\"switch_value\", ps, depth, &v->switch_value))";
pidl "\treturn False;";
pidl "";
+ } else {
+ pidl "v->switch_value = level;";
}
# Maybe check here that level and v->switch_value are equal?
- pidl "switch (level) {";
+ pidl "switch (v->switch_value) {";
indent;
foreach (@{$u->{ELEMENTS}}) {
@@ -420,19 +433,30 @@ sub ParseUnion($$$)
pidl "";
}
+ unless ($u->{HAS_DEFAULT}) {
+ pidl "default:";
+ pidl "\treturn False;";
+ pidl "";
+ }
+
deindent;
pidl "}";
pidl "";
pidl "return True;";
deindent;
pidl "}";
+ pidl "";
pidl "BOOL $dfn(const char *desc, $sn* v, uint32 level, prs_struct *ps, int depth)";
pidl "{";
indent;
DeclareArrayVariables($u->{ELEMENTS});
- pidl "switch (level) {";
+ if (defined($u->{SWITCH_TYPE})) {
+ pidl "switch (v->switch_value) {";
+ } else {
+ pidl "switch (level) {";
+ }
indent;
foreach (@{$u->{ELEMENTS}}) {
diff --git a/source4/pidl/pidl b/source4/pidl/pidl
index 07bfefa956..1e77b59be9 100755
--- a/source4/pidl/pidl
+++ b/source4/pidl/pidl
@@ -8,13 +8,15 @@
# released under the GNU GPL
=pod
+
=head1 NAME
-pidl - IDL Compiler written in Perl
+pidl - An IDL compiler written in Perl
=head1 SYNOPSIS
pidl --help
+
pidl [--outputdir[=OUTNAME]] [--parse-idl-tree] [--dump-idl-tree] [--dump-ndr-tree] [--ndr-header[=OUTPUT]] [--header[=OUTPUT]] [--ejs[=OUTPUT]] [--swig[=OUTPUT]] [--uint-enums] [--ndr-parser[=OUTPUT]] [--client] [--server] [--dcom-proxy] [--com-header] [--warn-compat] [--quiet] [--verbose] [--template] [--eth-parser[=OUTPUT]] [--diff] [--dump-idl] [--tdr-header=[OUTPUT]] [--tdr-parser[=OUTPUT]] [--samba3-header[=OUTPUT]] [--samba3-parser=[OUTPUT]] [--samba3-server=[OUTPUT]] [--samba3-template[=OUTPUT]] [--samba3-client[=OUTPUT]] [<idlfile>.idl]...
=head1 DESCRIPTION
@@ -95,8 +97,8 @@ packet-dcerpc-OUTNAME.h.
Pidl will read additional data from an ethereal conformance file if present.
Such a file should have the same location as the IDL file but with the
-extension I<cnf> rather then I<idl>. See below for details on the format of
-this file.
+extension I<cnf> rather then I<idl>. See L<Parse::Pidl::Ethereal::Conformance>
+for details on the format of this file.
=item I<--diff>
@@ -354,82 +356,26 @@ oleautomation, optional, pragma, propget, propputref, propput, readonly,
requestedit, restricted, retval, source, transmit_as, uidefault,
usesgetlasterror, vararg, vi_progid, wire_marshal.
-=head1 ETHEREAL CONFORMANCE FILES
-
-Pidl needs additional data for ethereal output. This data is read from
-so-called conformance files. This section describes the format of these
-files.
-
-Conformance files are simple text files with a single command on each line.
-Empty lines and lines starting with a '#' character are ignored.
-Arguments to commands are seperated by spaces.
-
-The following commands are currently supported:
-
-=over 4
-
-=item I<TYPE> name dissector ft_type base_type mask valsstring alignment
-
-Register new data type with specified name, what dissector function to call
-and what properties to give header fields for elements of this type.
-
-=item I<NOEMIT> type
-
-Suppress emitting a dissect_type function for the specified type
-
-=item I<PARAM_VALUE> type param
-
-Set parameter to specify to dissector function for given type.
-
-=item I<HF_FIELD> hf title filter ft_type base_type valsstring mask description
-
-Generate a custom header field with specified properties.
-
-=item I<HF_RENAME> old_hf_name new_hf_name
-
-Force the use of new_hf_name when the parser generator was going to
-use old_hf_name.
-
-This can be used in conjunction with HF_FIELD in order to make more then
-one element use the same filter name.
-
-=item I<STRIP_PREFIX> prefix
-
-Remove the specified prefix from all function names (if present).
-
-=item I<PROTOCOL> longname shortname filtername
-
-Change the short-, long- and filter-name for the current interface in
-Ethereal.
-
-=item I<FIELD_DESCRIPTION> field desc
-
-Change description for the specified header field. `field' is the hf name of the field.
-
-=item I<IMPORT> dissector code...
-
-Code to insert when generating the specified dissector. @HF@ and
-@PARAM@ will be substituted.
-
-=back
-
=head1 EXAMPLES
# Generating an ethereal parser
$ ./pidl --eth-parser -- atsvc.idl
- # Generating a TDR parser
+ # Generating a TDR parser and header
$ ./pidl --tdr-parser --tdr-header --header -- regf.idl
-=head1 VERSION
+ # Generating a Samba3 parser, client and server
+ $ ./pidl --samba3-parser --samba3-server --samba3-client -- dfs.idl
-This man page is correct for version 4.0 of the Samba suite. L<http://www.samba.org/>.
+ # Generating a Samba4 NDR parser, client and server
+ $ ./pidl --ndr-parser --ndr-client --ndr-server -- samr.idl
=head1 SEE ALSO
L<http://msdn.microsoft.com/library/en-us/rpc/rpc/field_attributes.asp>,
L<http://wiki.ethereal.com/DCE/RPC>,
-yapp(1)
+L<http://www.samba.org/>,
+L<yapp(1)>
=head1 LICENSE
@@ -438,7 +384,7 @@ pidl is licensed under the GNU General Public License L<http://www.gnu.org/licen
=head1 AUTHOR
pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim Potter and Jelmer
-Vernooij.
+Vernooij. The current maintainer is Jelmer Vernooij.
This manpage was written by Jelmer Vernooij, partially based on the original
pidl README by Andrew Tridgell.
@@ -536,7 +482,8 @@ my($opt_warn_compat) = 0;
sub ShowHelp()
{
print "perl IDL parser and code generator
-Copyright (C) tridge\@samba.org
+Copyright (C) Andrew Tridgell <tridge\@samba.org>
+Copyright (C) Jelmer Vernooij <jelmer\@samba.org>
Usage: pidl [options] [--] <idlfile> [<idlfile>...]