#
# Copyright (c) 2001-2012 NetApp, Inc., All Rights Reserved
#   Any use, modification, or distribution is prohibited
#   without prior written consent from NetApp, Inc.
#

## @summary AntivirusOnDemandCommandScanDir Task Module
## @author dl-nacl-dev@netapp.com
## @status shared
## @pod here

=head1 NAME

NACL::STask::AntivirusOnDemandCommandScanDir

=head1 DESCRIPTION

C<NACL::STask::AntivirusOnDemandCommandScanDir> provides a number of
well-defined but potentially complex or multi-step methods related to
AntivirusOnDemandCommandScanDirs in ONTAP.

It builds on top of, and is a derived class of C<NACL::C::AntivirusOnDemandCommandScanDir>,
and so it also provides methods that are more in the scope of
individual AntivirusOnDemandCommandScanDir-related commands. See 
C<NACL::C::AntivirusOnDemandCommandScanDir> for
details. This also means that a
C<NACL::STask::AntivirusOnDemandCommandScanDir> object may generally be
used in place of a component object.

=head1 ATTRIBUTES

=head2 command_interface

(Required) A component object that represents the host to which to send
commands.

=head2 name

(Required) The name of the AntivirusOnDemandCommandScanDir.

=head2 vserver

(Required) The vserver for which the scan is being performed.

=cut

package NACL::STask::AntivirusOnDemandCommandScanDir;

use base qw(NACL::C::AntivirusOnDemandCommandScanDir NACL::STask::STask);

# Pull implementation from mix-in
use NACL::STask::_Mixins::AntivirusOnDemandCommand qw(:all);

=head1 METHODS

=head2 create

    my $Avod_Scan_Dir_Obj = NACL::STask::AntivirusOnDemandCommand->create(
        command_interface  => $command_interface,
        name               => $command_name,
        vserver            => $vserver_name,
        nacltask_if_exists => $action,      # default 'die'
        nacltask_verify    => 0|1, # default '0'
        %other_options
    );

(Class method) Create an Antivirus On-Demand Command.  This method provides additional
services beyond what's inherent to the product's AntivirusOnDemandCommand creation
commands, as controlled and described by the new C<nacltask_if_exists> and
C<nacltask_verify> options.

=over

=item Options

=over

=item C<< nacltask_if_exists => $action >>

(Optional, defaults to "die") 
Specifies an action to be taken if the AntivirusOnDemandCommand already exists.

=over

=item C<die>

When set to "die", an exception is thrown if the AntivirusOnDemandCommand already exists.

=item C<reuse>

If a AntivirusOnDemandCommand of the same name already exists, reuse it.

=item C<purge>

If a AntivirusOnDemandCommand of the same name already exists, purge it and create a new one.

=back

=item C<< nacltask_verify => 0|1 >>

(Optional, defaults to 0)

When set to 0, verification is not performed.

When set to 1, it is verified that the created AntivirusOnDemandCommand has all of the attributes
specified.

=back

Note that it is also possible to perform the verification later by calling
L<taskverify_create|lib-NACL-STask-STask-pm/taskverify_create>. This can
be used for cases where ONTAP chooses to not set all attributes to the exact
values specified. In the call we can specify those attributes we want
verified.
           
=item C<< _was_created => \$scalar >>

(Optional)
When this option is provided a reference to a scalar variable, the variable
gets filled in with a boolean value describing whether the volume
was found (value will be 0; this scenario is possible when 
nacltask_if_exists => "reuse") or whether the aggregate was created (value will be 1).
This is necessary to determine whether the aggregate needs to be
cleaned up later.

    my $was_created;
    my $Avod_Scan_Dir_Obj = NACL::STask::AntivirusOnDemandCommandScanDir->create(
        nacltask_if_exists    => 'reuse',
        _was_created => \$was_created,
        %other_opts
    );
    # Operate on $Avod_Scan_Dir_Obj here
    # ...
    # Now determine whether to clean up the AntivirusOnDemandCommand, since we're not sure
    # whether we reused an existing command or created a new one
    if ($was_created) {
        # New avod command was created. Clean it up.
        $Avod_Scan_Dir_Obj->purge();
    }


=item Other options

All of the other various options are described in
L<< NACL::C::AntivirusOnDemandCommandScanDir->create|lib-NACL-C-AntivirusOnDemandCommandScanDir-pm/create >>

=back

=over

=item Exceptions

=over

=item C<NACL::C::Exceptions::AlreadyExists>

This type of exception is thrown when an attempt is made to create AntivirusOnDemandCommandScanDir when it already exists.

=item C<NACL::Exceptions::VerifyFailure>

This type of exception is thrown when verification fails for the created AntivirusOnDemandCommandScanDir.

=back

=back

=head2 modify

    NACL::STask::AntivirusOnDemandCommandScanDir->modify(
        command_interface => $command_interface,
        name              => $name,
        vserver           => $vserver,
        nacltask_verify   => $boolean,
        %other_opts
    );
    
                          or
                          
    $Avod_Scan_Dir_Obj->modify(nacltask_verify => $boolean, %other_opts);
    
Modifies properties of the scan. Also supports verification that all
of the properties got modified to the new values through the
C<nacltask_verify> argument.

=over

=item Options

=over

=item C<< nacltask_verify => 0 | 1 >>

(Optional, defaults to 0)
If the value is 1, then verifies that all the properties got modified to
the new values.

Note that this can be performed separately using the
L<taskverify_modify|lib-NACL-STask-STask-pm/taskverify_modify> method.

=back

=back

=head2 purge

    NACL::STask::AntivirusOnDemandCommandScanDir->purge(
        command_interface => $command_interface,
        name              => $name,
        vserver           => $vserver_name,
        %other_options,
    );

                          or

    $Avod_Scan_Dir_Obj->purge();

(Class or instance method) This method deletes an Antivirus On-Demand Command.

=over

=item Options

=over

=item C<< nacltask_if_purged => 'die' | 'pass' >>

(Optional, defaults to 'die')
What to do if the operation has already been deleted. A value of "die" will
result in an exception being throw, a value of "pass" will result in the
exception being suppressed.

=item C<< nacltask_verify => 0 | 1 >>

(Optional, defaults to 0)
Verifies that the operation has been deleted if the value is 1.

Note that this can be performed separately using the
L<taskverify_purge|lib-NACL-STask-STask-pm/taskverify_purge> method.

=item Other options

All of the other various options are described in
L<< NACL::C::AntivirusOnDemandCommandScanDir->delete|lib-NACL-C-AntivirusOnDemandCommandScanDir-pm/delete >>

=back

=back

=over

=item Exceptions

=over

=item C<NACL::C::Exceptions::AntivirusOnDemandCommandScanDir::DoesNotExist>

This type of exception is thrown when an attempt is made to delete AntivirusOnDemandCommandScanDir that does not exists.

=item C<NACL::C::Exceptions::AntivirusOnDemandCommandScanDir::InUse>

This type of exception is thrown when an attempt is made to delete AntivirusOnDemandCommandScanDir when it is in use.

=item C<NACL::Exceptions::VerifyFailure>

This type of exception is thrown when verification fails for the deleted AntivirusOnDemandCommandScanDir.

=back

=back

=cut

1;