mirror of
https://github.com/samba-team/samba.git
synced 2025-02-25 17:57:42 +03:00
r10829: Documentation updates
Update TODO Some small fixes to the modules (This used to be commit 0c53e7c3cf7fd91fd34c48a5e68c1bcf70569854)
This commit is contained in:
Jelmer Vernooij
Gerald (Jerry) Carter
parent
b1b6eb7b67
commit
848dff8f0d
@ -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
|
||||
|
||||
@ -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;
|
||||
|
||||
@ -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;
|
||||
|
||||
@ -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;
|
||||
|
||||
@ -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
|
||||
};
|
||||
}
|
||||
|
||||
@ -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}}) {
|
||||
|
||||
@ -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}}) {
|
||||
|
||||
@ -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>...]
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user