github.com/vmware/govmomi@v0.43.0/client.go (about)

     1  /*
     2  Copyright (c) 2014-2023 VMware, Inc. All Rights Reserved.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8  http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  /*
    18  This package is the root package of the govmomi library.
    19  
    20  The library is structured as follows:
    21  
    22  # Package vim25
    23  
    24  The minimal usable functionality is available through the vim25 package.
    25  It contains subpackages that contain generated types, managed objects, and all
    26  available methods. The vim25 package is entirely independent of the other
    27  packages in the govmomi tree -- it has no dependencies on its peers.
    28  
    29  The vim25 package itself contains a client structure that is
    30  passed around throughout the entire library. It abstracts a session and its
    31  immutable state. See the vim25 package for more information.
    32  
    33  # Package session
    34  
    35  The session package contains an abstraction for the session manager that allows
    36  a user to login and logout. It also provides access to the current session
    37  (i.e. to determine if the user is in fact logged in)
    38  
    39  # Package object
    40  
    41  The object package contains wrappers for a selection of managed objects. The
    42  constructors of these objects all take a *vim25.Client, which they pass along
    43  to derived objects, if applicable.
    44  
    45  # Package govc
    46  
    47  The govc package contains the govc CLI. The code in this tree is not intended
    48  to be used as a library. Any functionality that govc contains that _could_ be
    49  used as a library function but isn't, _should_ live in a root level package.
    50  
    51  # Other packages
    52  
    53  Other packages, such as "event", "guest", or "license", provide wrappers for
    54  the respective subsystems. They are typically not needed in normal workflows so
    55  are kept outside the object package.
    56  */
    57  package govmomi
    58  
    59  import (
    60  	"context"
    61  	"net/url"
    62  
    63  	"github.com/vmware/govmomi/property"
    64  	"github.com/vmware/govmomi/session"
    65  	"github.com/vmware/govmomi/vim25"
    66  	"github.com/vmware/govmomi/vim25/soap"
    67  	"github.com/vmware/govmomi/vim25/types"
    68  )
    69  
    70  type Client struct {
    71  	*vim25.Client
    72  
    73  	SessionManager *session.Manager
    74  }
    75  
    76  // NewClient creates a new client from a URL. The client authenticates with the
    77  // server with username/password before returning if the URL contains user information.
    78  func NewClient(ctx context.Context, u *url.URL, insecure bool) (*Client, error) {
    79  	soapClient := soap.NewClient(u, insecure)
    80  	vimClient, err := vim25.NewClient(ctx, soapClient)
    81  	if err != nil {
    82  		return nil, err
    83  	}
    84  
    85  	c := &Client{
    86  		Client:         vimClient,
    87  		SessionManager: session.NewManager(vimClient),
    88  	}
    89  
    90  	// Only login if the URL contains user information.
    91  	if u.User != nil {
    92  		err = c.Login(ctx, u.User)
    93  		if err != nil {
    94  			return nil, err
    95  		}
    96  	}
    97  
    98  	return c, nil
    99  }
   100  
   101  // Login dispatches to the SessionManager.
   102  func (c *Client) Login(ctx context.Context, u *url.Userinfo) error {
   103  	return c.SessionManager.Login(ctx, u)
   104  }
   105  
   106  // Logout dispatches to the SessionManager.
   107  func (c *Client) Logout(ctx context.Context) error {
   108  	// Close any idle connections after logging out.
   109  	defer c.Client.CloseIdleConnections()
   110  	return c.SessionManager.Logout(ctx)
   111  }
   112  
   113  // PropertyCollector returns the session's default property collector.
   114  func (c *Client) PropertyCollector() *property.Collector {
   115  	return property.DefaultCollector(c.Client)
   116  }
   117  
   118  // RetrieveOne dispatches to the Retrieve function on the default property collector.
   119  func (c *Client) RetrieveOne(ctx context.Context, obj types.ManagedObjectReference, p []string, dst interface{}) error {
   120  	return c.PropertyCollector().RetrieveOne(ctx, obj, p, dst)
   121  }
   122  
   123  // Retrieve dispatches to the Retrieve function on the default property collector.
   124  func (c *Client) Retrieve(ctx context.Context, objs []types.ManagedObjectReference, p []string, dst interface{}) error {
   125  	return c.PropertyCollector().Retrieve(ctx, objs, p, dst)
   126  }
   127  
   128  // Wait dispatches to property.Wait.
   129  func (c *Client) Wait(ctx context.Context, obj types.ManagedObjectReference, ps []string, f func([]types.PropertyChange) bool) error {
   130  	return property.Wait(ctx, c.PropertyCollector(), obj, ps, f)
   131  }
   132  
   133  // IsVC returns true if we are connected to a vCenter
   134  func (c *Client) IsVC() bool {
   135  	return c.Client.IsVC()
   136  }